Canvas 2D Web Apps/iBooks HTML Widgets

This chapter discusses the differences between HTML web apps for desktop browsers and web apps that are used as iBooks HTML widgets. It assumes that you are familiar with the chapter Getting Started with HTML Web Apps. If you haven't read that chapter yet, you should read it first.

What are iBooks HTML Widgets?
iBooks is a free application by Apple to buy, download, and read particular electronic books (also called “iBooks”) on iOS devices. Apple also offers the free application iBooks Author for MacOS X computers to create and publish such electronic books.

iBooks Author allows authors to include multiple built-in widgets (e.g. viewers for videos, 3D models, or galleries of images). It also allows to include user-defined “HTML widgets,” which are special HTML web apps. This chapter will only discuss the differences between iBooks HTML widgets and the standard HTML web apps for desktop browsers that have been discussed in chapter Getting Started with HTML Web Apps. The discussion is based on an Apple support document, which provides additional information.

Preparing an iBooks HTML Widget
In order to create a HTML widget for iBooks, you need at least 3 files (note that none of the file names may contain control characters):
 * 1) The HTML file of the web app as described in chapter Getting Started with HTML Web Apps except that it should not require internet access; i.e., all required files (in particular image files) should be stored in the same folder as the HTML file or in one of its subfolders. In this example, the HTML file is called.
 * 2) A PNG image file that must be called  which provides a preview of the web app.
 * 3) A plain text file that must be called  which specifies some properties of the specific web app. The example is for a screen-filling widget in landscape orientation of size 1024×768 with the HTML file.
 * 4) Any other files that the web app requires (in particular image files). In this example: HTML5_Shiny_Icon.png.

In this example, the  file looks like this:  <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">  CFBundleDevelopmentRegion English CFBundleDisplayName my web app CFBundleIdentifier com.dummy.MyWebApp CFBundleName mywebapp CFBundleShortVersionString 1.0 	 CFBundleVersion 1.0 	 Height 768 	 MainHTML ibooks_basic.html Width 1024 	 IBNotifiesOnReady The keys are relatively easy to understand and most are actually optional. However, it is important that  is set to the correct file name of the web app; in this example:. If  and   are not specified then the size of the   image is used for the web app. The key  can be set to true if the web app informs the iBooks app when it is ready for rendering in order to avoid any flickering when starting the widget. More information about this is provided in an Apple support document.

To create a widget from these files, you should copy them into one folder on a MacOS X computer and rename the folder to the name of the widget with the extension. (The icon of the folder will change and the content will be hidden; but you can still see it by right-clicking the widget folder and choosing “Show Package Content” from the pop-up menu.) That's it: you have created a iBooks HTML widget.

Inserting an iBooks HTML Widget into an iBook
Once you have this widget folder, you can open a book project in iBooks Author and create an empty HTML widget template by choosing Insert > Widget > HTML from the main menu. In the Inspector window (if it isn't visible, you can open it with View > Show Inspector from the main menu), you should choose the right-most tab icon (“Widget Inspector”) and then the Interaction settings. Click on Choose... and select the widget folder in the file selector dialog. That's it. You can test the widget on your computer by clicking on Edit HTML below the widget representation in the book. In order to see the widget on an iPad, you should connect the iPad, open the iBooks app on the iPad, and select File > Preview from the main menu of iBooks Author.

Additional Information
There are no issues with the viewport of a widget in iBooks: it always has the size that is specified in the  file (or — if no size is specified there — the size of the   image). Even if the orientation of the iPad is changed, that size (in CSS pixels) stays the same but iBooks will scale the widget to fit the screen. Note that it might be a good idea to use landscape orientation for widgets because in that case they are either displayed full-screen (if the iPad is held in landscape orientation) or the title and caption are displayed above and below the widget (if the iPad is held in portrait orientation).

By default, iBooks supports some two-finger gestures to allow users to interact with widgets. You can disable these gestures for your web app as discussed in the chapter Getting Started with iOS Web Apps.