Wikibooks

Canvas 2D Web Apps/iBooks HTML Widgets

< Canvas 2D Web Apps

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?

edit

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

edit

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 ibooks_basic.html.
  2. A PNG image file that must be called Default.png which provides a preview of the web app.
  3. A plain text file that must be called Info.plist 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 ibooks_basic.html.
  4. Any other files that the web app requires (in particular image files). In this example: HTML5_Shiny_Icon.png.

In this example, the Info.plist file looks like this: 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleDevelopmentRegion</key>
	<string>English</string>
	<key>CFBundleDisplayName</key>
	<string>my web app</string>
	<key>CFBundleIdentifier</key>
	<string>com.dummy.MyWebApp</string>
	<key>CFBundleName</key>
	<string>mywebapp</string>
	<key>CFBundleShortVersionString</key>
	<string>1.0</string>
	<key>CFBundleVersion</key>
	<string>1.0</string>
	<key>Height</key>
	<integer>768</integer>
	<key>MainHTML</key>
	<string>ibooks_basic.html</string>
	<key>Width</key>
	<integer>1024</integer>
	<key>IBNotifiesOnReady</key>
	<false/>
</dict>
</plist>

The keys are relatively easy to understand and most are actually optional. However, it is important that MainHTML is set to the correct file name of the web app; in this example: ibooks_basic.html. If Width and Height are not specified then the size of the Default.png image is used for the web app. The key IBNotifiesOnReady 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 .wdgt. (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

edit

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

edit

There are no issues with the viewport of a widget in iBooks: it always has the size that is specified in the Info.plist file (or — if no size is specified there — the size of the Default.png 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.


page traffic for 90 days

< Canvas 2D Web Apps

Unless stated otherwise, all example source code on this page is granted to the public domain.
Retrieved from "https://en.wikibooks.org/w/index.php?title=Canvas_2D_Web_Apps/iBooks_HTML_Widgets&oldid=2549775"