Languages

iBooks Author: About HTML widget creation

You can create HTML5 widgets for use with books you make 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 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.

Notes

  • If your book includes HTML widgets that contain files with control characters in the filenames, it cannot be published to the iBooks Store. Before you create your widget bundle, make sure none of the files contained in the bundle use these characters in the filename. Do not use custom folder icons.
  • Avoid including folders with these names inside your widget bundle:
    • Resources/
    • Support Files/Resources/
    • Contents/Resources/
  • If you are creating content for iPads or Macs that have 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 or Macs that have a Retina display. 
  • If you want your widget to take up the full screen when zoomed in, 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.
  • 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.” 

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, to be displayed 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 is 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 are not compatible. You should not use these keys:

AllowFileAccessOutsideOfWidget Widgets in books created with iBooks Author cannot access files in the general file system.
AllowFullAccess Shorthand for a list of other access keys, some of which are not compatible.
AllowInternetPlugins Internet plugins, such as Flash, are unavailable in books created with iBooks Author. Movies and audio can be included via the HTML5 <video> and <audio> elements, respectively.
Note: Movies and audio inside of HTML widgets will not be DRM-protected.
AllowJava Widgets in books created with iBooks Author cannot include Java content.
AllowSystem Widgets in the books created with iBooks Author cannot access system commands.
Plugin Widgets in books created with iBooks Author cannot include a Cocoa plugin component.

iBooks Author ignores these keys: 

CloseBoxInsetX Widgets in iBooks Author and iBooks do not display a close decoration.
CloseBoxInsetY  

 

Fonts iBooks Author widgets cannot use bundled fonts.

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 or with OS X Mavericks. 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;
}

Developing for both iOS and OS X Mavericks

iOS and OS X use fundamentally different input types, so when you create your HTML widgets for iBooks Author, you will need to make sure you accommodate for both touch handling and mouse handling if you would like to use any type of control not handled by standard gestures.

 

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.

Important: Mention of third-party websites and products is for informational purposes only and constitutes neither an endorsement nor a recommendation. Apple assumes no responsibility with regard to the selection, performance or use of information or products found at third-party websites. Apple provides this only as a convenience to our users. Apple has not tested the information found on these sites and makes no representations regarding its accuracy or reliability. There are risks inherent in the use of any information or products found on the Internet, and Apple assumes no responsibility in this regard. Please understand that a third-party site is independent from Apple and that Apple has no control over the content on that website. Please contact the vendor for additional information.
Last Modified: Oct 22, 2013
Helpful?
Yes
No
Not helpful Somewhat helpful Helpful Very helpful Solved my problem
Print this page
  • Last Modified: Oct 22, 2013
  • Article: HT5068
  • Views:

    151718
  • Rating:
    • 63.0

    (656 Responses)

Additional Product Support Information

Start a Discussion
in Apple Support Communities
See all questions on this article See all questions I have asked