iBooks Author: About HTML widget creation

iBooks Author supports HTML5 widgets (with the extension .wdgt).

To create an HTML widget for iBooks Author, use a text editor or web content creation app to create the following files: 

• Main HTML file: This file is the main part of the widget. It can have any name you like, but its extension must be ".html". You can put CSS and JavaScript inside the main HTML file, or add .css and .js files to the widget bundle and set the main HTML file to load them. In these files, you can use any technique or trick that you would use when designing a webpage. In general, you use HTML to define the structure of your widget, CSS to provide the visual style, and JavaScript to support interactivity. 
• Default.png: This is the image that will appear on the page, and that users will tap to open your widget. Its name must be "Default.png," with a capital letter "D". The easiest way to create a Default.png is to take a screenshot of your main HTML file running in a web content creation app or web browser. When your widget is active, it will be the size of the Default.png, unless you specify a different size in the Info.plist.
• Info.plist: This file gives iBooks Author and iBooks the information they need to run your widget. Its name must be "Info.plist." Details and a sample are below. 

Once you've created the three required files (and perhaps some optional files, such as CSS or JavaScript), assemble them into a widget bundle:

1. Using the Finder, create a folder, and add the files to it.
2. Rename the folder and add a .wdgt extension to the folder name. This will create the widget bundle, and the folder icon will change to a widget icon.

Your widget is now ready to be added to iBooks Author. 

Note: If your book includes HTML widgets that contain files with control characters in the filenames, it cannot be published to the iBookstore. Before you create your widget bundle, make sure none of the files contained in the bundle uses these characters in the filename; do not use custom folder icons.

Note: Avoid including folders with these names inside your widget bundle:

• Resources/
• Support Files/Resources/
• Contents/Resources/

Note: If you are creating content for iPads with a Retina display:

• When coding your HTML, CSS, and JavaScript files, follow the standard protocol for creating websites with Retina (2x) graphics. 
• Your widget bundle should include a Default@2x.png file, which should be double the resolution of the Default.png file. You won’t be able to view this file in iBooks Author, but it will display in iBooks on iPads with a Retina display. 

Note: If you want your widget to take up the full screen when tapped on iPad, make the Default.png 768 by 1024 pixels and the Default@2x.png 1536 by 2048 pixels. If you want your widget to display smaller than full-screen, make the Default.png the dimensions at which you want your widget to display (for example, 600 by 900), and make the Default@2x.png twice that dimension.

The Info.plist 

A basic widget’s Info.plist contains some required keys and some optional keys. These keys are listed below along with their definitions and some example values for a widget called “Hello World.” 

 The complete Info.plist for a widget 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>Hello World</string>
	<key>CFBundleIdentifier</key>
	<string>com.apple.widget.HelloWorld</string>
	<key>CFBundleName</key>
	<string>Hello World</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>HelloWorld.html</string>
	<key>Width</key>
	<integer>1024</integer>
	<key>IBNotifiesOnReady</key>
	<true/>
</dict>
</plist>

Restrictions and limitations

Some features are not compatible. You should not use these keys:

iBooks Author ignores these keys: 

Movie and Audio Requirements

You cannot use media that have ".m4v" or ".m4p" file extensions. 

It is recommended that you use H.264 video in an MPEG-4 container with an ".mp4" file extension.

For audio, it is recommended that you use AAC audio in an MPEG-4 container with an ".m4a" file extension.

Note: Video and audio media in HTML widget bundles are not DRM-protected.

Note: In some cases, movies and audio files in HTML widgets may not play in iBooks Author but will play in iBooks. If you are unable to play a movie or audio file in your widget in iBooks Author, try previewing on iPad. This should show you how the file will play in your completed book.

Localization

Localized strings and assets are not supported in iBooks Author. Therefore, user-visible text strings should be included inline in the target language.

Clipped elements

If an element such as a <video> element appears clipped on one side, it may be because it is expanding to fill a space larger than what is visible. Check the CSS for "width:auto" in the #video selector and change it to reflect the actual dimensions. For example, if your widget contains a video whose dimensions are 960 by 540, then check the CSS for the relevant selector and explicitly set the width and height to the correct values:

#video   {
	width: 960;
	height: 540;
}

Opening the HTML widget

Depending on how complicated your HTML widget is, your readers may experience a flash during HTML initialization when they open the widget in iBooks. To avoid the flash, modify your widget so that it tells iBooks when to switch from displaying the Default.png file to displaying the running HTML widget.

There are three modifications you must make to add this optional functionality:

1. Add a "IBNotifiesOnReady" item set to "true" in the widget's info.plist file, so iBooks knows this widget will tell it when to switch to displaying the running HTML widget:
   

   <key>IBNotifiesOnReady</key>
   <true/>

2. Set your widget to load the Apple JavaScript library in the HEAD portion of the HTML file:
   

   <script type="text/javascript" src="AppleClasses/AppleWidget.js"> </script>
   

   Note: AppleWidget.js is already present on the iPad, and you do not need to include it in your widget bundle.


3. Set your widget to let iBooks know when the HTML is initialized, and iBooks can switch from showing the Default.png file to displaying the running HTML widget by calling (in JavaScript included in the HEAD portion of the HTML file):
   

   widget.notifyContentIsReady()

Important: If you choose to modify your HTML widget to avoid the flash, be sure to do all three of the above steps. You must compete all of the steps for this to function properly.

About posting to external Web Services

HTML widgets can only post to external web services if those web services have implemented the appropriate CORS (Cross-Origin Resource Sharing) headers.