A quick update to my post from last week. Xcode became available as an App in the Mac App Store, and it no longer includes Dashcode by default. That means you need to download Dashcode separately, which requires an Apple Developer account. Apple gave the impression that Dashcode was included with iBooks Author, which doesn’t appear to be the case. If you don’t have Dashcode, don’t worry, you won’t need it for today.

This is part 2 of my series on Interactive Widgets for iBooks Author.

1. Using DashCode to create an interactive widget
2. Creating an interactive widget without Dashcode (This article)
3. Creating a RemObjects SDK client widget
4. Creating a Data Abstract client widget

If you already have an existing HTML5 & JavaScript “applet”, it is the best solution to use, since you can easily adapt it to work as an interactive widget for iBooks. There are 3 required parts for an interactive HTML widget:

1. Main HTML file – You can have other script files, but one HTML file needs to be your main file. The name is flexible.
2. Default.png – This is the image that is displayed when your widget is not activated and it is viewed on the book page. It must be named Default.png.
3. Info.plist – This describes your interactive widget to iBooks. It must be named Info.plist.

The Main HTML and Default.png are easy to make from scratch if you have some idea what you want, but the Info.plist is a little more complicated, so lets look at it first.

The Info.plist File

A p-list file, or Property List file, is an XML file that stores serialized objects. It contains a dict element containing key/ value pairs. The Info.plist file in your widget needs to contain specific keys. It should look something like this:

You can copy this p-list and save it to disk as Info.plist, as a start for your widget. I’ve cleaned this p-list down to the minimum elements. Let’s discuss the purpose of each element in detail.

AllowNetworkAccess key

The AllowNetworkAccess key is required (according to the documentation) if your widget is going to access the network (local or Internet). If your widget is running on the Dashboard, this is true, but in my tests it isn’t required in iBooks for network access. I would suggest leaving it in if you want network access, just in case. The true element is the value.

CFBundleIdentifier and CFBundleName keys

The CFBundleIdentifier and CFBundleName keys and their values are required, but from what I have seen, the values are not used in iBooks. Removing them, however, results in the widget no longer working. Feel free to change the values if you like for your Widget. They may become relevant in the future.

MainHTML key

The MainHTML key specifies the main HTML file the widget uses. This is the only value you may actually need to change to make your widget work. So whatever you name your main HTML file needs to be the value here. Alternatively, you can just rename your main HTML file index.html and leave the p-list above as is.

There are other key elements that are included by Dashcode, and are required for widgets on the Dashboard, but they are not required, nor do they seem to have an effect, in iBooks.

The Default.png File

The Default.png file serves two very important purpose. The first being that it is the “in page” preview of your widget when it is not active, the second that it defines the size and aspect ratio of your widget when displayed in active mode.

The easiest way to create a preview of your widget is to create a screen shot of your widget running in your browser on the desktop. While your widget is running, press Command-Shift-4 and then use the mouse to select the area to capture. While you are capturing, it tells you the size of the image you are capturing. When you’re done, a new “Screen Shot ????.png” file is saved to the desktop. Simply rename it Default.png and move it into the folder with the rest of your widget.

As a Preview

When selecting the screen shot for the preview, there are a few things to keep in mind.

• It will typically be displayed much smaller when embedded in the page. So if you are relying on small details, they will most likely be lost.
• When the widget activates, the Default.png zooms to actual size and is then replaced by the running widget. So if your Default.png does not line up with the running widget, it will be very obvious when that occurs. A transition on startup might be a good idea if you know your Default.png won’t line up.
• The Default.png should be appealing and give some idea of what information or interactivity the widget provides.

The Widget Size

The dimensions of your Default.png determine the running dimensions of your widget. The iPad has a resolution of 1024×768. Your Default.png can actually be larger than that. If that happens, iBooks will automatically reduce the size of the running widget, maintaining the aspect ratio so it fits on the screen. Also, your widget can run in portrait or landscape mode, which may result in size reduction if the width is greater than 768.

The Main HTML File

The Main HTML File is the heart of your widget. Its name must be referenced from the value for MainHTML in the Info.plist. This HTML file can contain JavaScript and CSS Styles, or it can reference external files that are also bundled in the widget. It can also reference images contained in your widget. These other files that the Main HTML file reference do not need to be referenced in the Info.plist.

Test your Main HTML file in Safari, or better yet on the iPad, to get an idea what it will look and behave like in iBooks. There are subtle differences between different browsers.

iBooks has fairly robust HTML and JavaScript support as we will see in future parts of this series. That means you can make use of JavaScript libraries like jQuery or JavaScript tools like Tumult Hype.

Remember not to include any JavaScript alerts, as they will cause iBooks to hang.

The Package

All of these files need to be placed in a package. This is actually very easy. Simply place them in a single Folder in Finder. Then move up the path to the parent folder. Select the folder and rename it (press return), adding a .wdgt extension. Finder will prompt you to be sure you want to do that.

![Finder Dialog: Are you sure you want to add the extension ".wdgt" to the end of the name?](GHOST_URL/wp-content/uploads/2012/02/Are-you-sure-you-want-to-add-the-extension-.wdgt-to-the-end-of-the-name.png "Are you sure you want to add the extension ".wdgt" to the end of the name?")

Once you click Add, the Folder will be replaced with a widget icon.

![Widget ".wdgt" icon](GHOST_URL/wp-content/uploads/2012/02/wdgt-icon.png "Widget ".wdgt" icon")

Remember:

• If you double-click this icon, it gets installed in the Dashboard and deleted from Finder. Back it up first!
• Even though finder treats this as a single package, it is still physically a Folder with individual files in it. So if you upload it or move it to a non-Mac computer, it will appear as such.
• You can still access the contents as if it were a folder by right-clicking on it and selecting Show Package Contents.

Adding to iBooks Author

You are now ready to add the widget to iBooks Author. The method is the same I outlined in part 1. You can either drag it onto the widget element in iBooks Author, or use the inspector to Choose the widget.

Conclusion

If you have existing HTML that you want to reuse as an interactive widget, bypassing the Dashcode templates is the easiest solution. The HTML and JavaScript runs almost exactly the same as it does in Safari on the desktop. iBooks HTML and JavaScript support is fairly complete, allowing for very powerful interactive widgets.

Things to Remember:

1. Remember the Default.png, Info.plist and Main HTML file.
2. Use a working Info.plist (copy it from above); it must reference your Main HTML file by name.
3. No JavaScript alert statements.
4. The dimensions of your Default.png determine the dimensions of your widget when it runs.
5. Double-clicking a .wdgt package installs it in the Dashboard and deletes it from Finder. Back it up!