About HTML widget creation in iBooks Author

Learn how to use HTML5 widgets in the books you create in iBooks Author.

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 these 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 load them from the main HTML file. In these files, you can use any technique or trick that you'd use to design a webpage. 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 users will see on the page and tap to open your widget. You must name it "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 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. 

After you create the three required files (and any optional files, such as CSS or JavaScript), add them to 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.
  3. Add your widget to iBooks Author.

Tips for creating widgets

If the HTML widgets in your book contain files with control characters in the filenames, you can't publish it to the iBooks Store. Before you create your widget bundle, make sure the files in the bundle don't use these characters in the filename.

Don't use custom folder icons.

Avoid including folders with these names in your widget:

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

If you're creating content for an iPad or Mac with a Retina display:

  • In your HTML, CSS, and JavaScript files, use the standard protocol for creating websites with Retina (2x) graphics. 
  • Include a Default@2x.png file in your widget. This file should be double the resolution of the Default.png file. You can't view this file in iBooks Author, but it will appear in iBooks on an iPad or Mac with a Retina display.

If you want your widget to take up the full screen when zoomed in, make Default.png 768 x 1024 pixels and Default@2x.png 1536 x 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 x 900), and make the Default@2x.png twice that dimension.

Learn more about optimizing books made with iBooks Author.

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.” 

Key Example value Required Definition
CFBundleDevelopmentRegion English Optional A string that specifies the native region for the bundle. This usually corresponds to the native language of the person who created the bundle. 
CFBundleDisplayName Hello World Required A string that contains the actual name of the widget. This will display in iBooks Author and iBooks.
CFBundleIdentifier com.apple.widget.HelloWorld Required A string that uniquely identifies the widget, in reverse domain format.
CFBundleName Hello World Optional A string that contains the name of your widget. It must match the name of the widget bundle in the Finder, minus the .wdgt file extension.
CFBundleShortVersionString 1.0 Optional A string that gives the shortened version number of the widget. It's often the same as CFBundleVersion.
CFBundleVersion 1.0 Optional A string that gives the version number of the widget.
Height 768 Optional A number that gives the height, in pixels, of your widget. If not specified, the height of Default.png is used.
MainHTML HelloWorld.html Required A string that gives the name of the HTML file that implements your widget.
Width 1024 Optional A number that gives the width, in pixels, of your widget. If not specified, the width of Default.png is used.
IBNotifiesOnReady <true/> Optional When set to true, the widget tells iBooks when to switch from displaying the Default.png to displaying the running HTML widget. 

 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 aren't compatible. You shouldn't use these keys:

Key Description
AllowFileAccessOutsideOfWidget Widgets in books created with iBooks Author can't access files in the general file system.
AllowFullAccess Shorthand for a list of other access keys, some of which aren't compatible.
AllowInternetPlugins Internet plugins, such as Flash, are unavailable in books created with iBooks Author. You can include movies and audio using the HTML5 <video> and <audio> elements.
Movies and audio inside of HTML widgets won't be DRM-protected.
AllowJava Widgets in books created with iBooks Author can't include Java content.
AllowSystem Widgets in the books created with iBooks Author can't access system commands.
Plugin Widgets in books created with iBooks Author can't include a Cocoa plugin component.

iBooks Author ignores these keys: 

Key Description
CloseBoxInsetX Widgets in iBooks Author and iBooks don't display a close decoration.
CloseBoxInsetY  

 

Fonts iBooks Author widgets can't use bundled fonts.

Movie and Audio Requirements

You can't use media that has .m4v or .m4p file extensions. Use one of these formats with an .mp4 file extension:

  • H.264 video: Up to 720p, 60 frames per second, High Profile level 4.2 with AAC-LC audio up to 160 kbps, 48 kHz, stereo audio. Video shared to file from iMovie 10 using the HD 720p option will use these settings.
  • MPEG-4 video: Up to 2.5 Mbps, 640 x 480 pixels, 30 frames per second, Simple Profile with AAC-LC audio up to 160 kbps per channel, 48kHz, stereo audio.

For audio, you should use AAC (8 to 320 Kbps, 48 kHz stereo) with an .m4a file extension.

Video and audio media in HTML widget bundles aren't DRM-protected.

In some cases, movies and audio files in HTML widgets might not play in iBooks Author but will play in iBooks. If you can't play a movie or audio file in your widget in iBooks Author, try previewing on iPad or with OS X Mavericks. This should show you how the file will play in your completed book.

Localization

Localized strings and assets aren't supported in iBooks Author. You should include user-visible text strings inline in the target language.

Clipped elements

If an element, such as <video>, appears clipped on one side, it might be expanding to fill a space larger than what's 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 x 540, then check the CSS for the relevant selector and set the width and height to the correct values:

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

Developing for both iOS and OS X Mavericks

iOS and OS X use different input types. When you create your HTML widgets for iBooks Author, you will need to accommodate both touch and mouse handling if you want to use controls that aren't handled by standard gestures.

Opening the HTML widget

Depending on how complicated your HTML widget is, your readers might see 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.

To modify your HTML widget to avoid the flash, you must compete all of these steps:

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>

AppleWidget.js is already present on iPad, and you don't 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()

Posting to external Web Services

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

Last Modified:
Helpful?

Additional Product Support Information

Start a Discussion

in Apple Support Communities
See all questions on this article See all questions I have asked
United States (English)