This article has been archived and is no longer updated by Apple.

Create HTML5 widgets for iBooks Author

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

iBooks Author supports HTML5 widgets, which have the filename extension .wdgt. To make an HTML5 widget, use a text editor or content creation app to create these three 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, you can add .css and .js files to the widget bundle and load them from the main HTML file. You can use any technique that you'd use to design a webpage. Use HTML to define the widget’s structure, CSS to provide the visual style, and JavaScript to make it interactive.

  • Default.png file: 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. This is the image that readers see on the page and tap to open the widget. In a web browser or web content creation app, take a screenshot of your main HTML file. Name it “Default.png,” and be sure to use a capital letter "D." When your widget is active, it's the size of the Default.png file. You can change its size in the Info.plist file.

  • Info.plist file: This file gives iBooks Author and Apple Books the information that they need to run your widget. The filename must be "Info.plist."

After you create these required files, create any optional files that you want, like CSS or JavaScript files. Then, add them all to a widget bundle:

  1. In the Finder, create a folder.

  2. Add the files to your new folder.

  3. Rename the folder and add a .wdgt extension to the folder name to create the widget bundle. The folder icon changes to a widget icon.

  4. Add your widget to iBooks Author.

Tips for creating widgets

Before you create your widget bundle, make sure that no file in the bundle has a control character in its filename. If one does, you can't publish the book to the Book Store in Apple Books.

If you set your widget to play automatically, it can't access the Internet.

Don't use custom folder icons, and avoid these folder names in your widget:

  • Resources/

  • Support Files/Resources/

  • Contents/Resources/

To optimize your widget for a Retina display:

  • In your HTML, CSS, and JavaScript files, use the standard protocol for websites with Retina (2x) graphics.

  • Include a Default@2x.png file in your widget. Make the file twice the resolution of the Default.png file. You can't see this file in iBooks Author, but you can see it in Apple Books on a Retina display.

Learn more about how to optimize books that you make with iBooks Author.

The Info.plist

A basic widget’s Info.plist file contains some required keys and some optional keys. This table lists these keys, 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 Apple Books.

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

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 Apple Books 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>

Key restrictions and limitations

Don’t use these keys; the features aren't compatible:

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 Apple Books don't display a close decoration.

CloseBoxInsetY

Fonts

iBooks Author widgets can't use bundled fonts.

Video 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. Videos that open in iMovie 10 with the HD 720p option 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, 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.

If a movie or audio file doesn't play in your widget in iBooks Author, preview it on your iPhone, iPad or Mac. This shows how the file will play in your completed book.

Localization

iBooks Author doesn't support localized strings and assets. Include text strings in the target language that the reader can see inline.

Fix clipped elements

An element, such as <video>, might appear clipped on one side. This can happen if its dimensions are larger than the available space. Find the CSS for "width:auto" in the #video selector and change it to reflect the actual dimensions. For example, your widget might contain a video whose dimensions are 960 x 540. Check the CSS for the relevant selector and set the width and height to the correct values:

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

Develop for iOS and macOS

iOS and macOS use different input types. You can accommodate both touch and mouse input when you create your HTML widgets for iBooks Author.

Avoid a flash when readers open the HTML widget

If your HTML widget is very complicated, your readers might see a flash when they open it in Apple Books. To avoid this, update your widget to tell Apple Books when to switch from the Default.png file to the HTML widget:

1. Add an "IBNotifiesOnReady" item that's set to true in the widget's Info.plist file. This lets Apple Books know that the widget will tell it when to switch to the 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>

iOS and macOS already have AppleWidget.js, so you don't have to include it in your widget bundle.

3. Set your widget to notify Apple Books when the HTML is initialized. In the JavaScript that's in the <head> portion of the HTML file, call:

widget.notifyContentIsReady()

Post to an external web service

You can post HTML widgets to external web services only if they use the correct Cross-Origin Resource Sharing (CORS) headers.

Published Date: