HTML5 Widget Bundle
- Information property list file (Info.plist) gives iBooks Author and iBooks the information on how to run the widget. Its name must be “Info.plist” with a capital letter “I”. This is a structured text file that contains essential configuration information for a bundled executable, which is in our case our HTML5 widget.
- Widget cover image (Default.png) is the image that will appear on the ebook page that users will tap to activate the widget. The name of this file must be “Default.png,” with a capital letter “D”. When the widget is activated, it will be the size of the Default.png image, unless you specify a different size in the Info.plist file (see below). If you want to utilize retina displays, just supply Default@2x.png file as well, and iOS device will know when to use which one.
First two files you can create using the regular text editor or any IDE of your choice. For Default.png use whatever you think looks appropriate for your readers. Once you have these three files you have a foundation for your widget. Put these files in one folder and name the folder with some descriptive name, but keep in mind that this name does not have to uniquely identify your widget. This is done with some specific elements inside the Info.plist file. You can and probably should add appropriate subfolders inside your widget folder for images, scripts, stylesheets, etc. To test your widget you should simply use your browser (Chrome or Safari for example) to open the main HTML file and verify that everything works fine. Usually these browsers have developer mode which will allow you to simulate widget execution inside the iOS device browser. This is a good test having in mind that iBooks app uses pretty much that same browser.
When everything is nicely packaged and tested you should rename the main widget folder by adding the .wdgt extension to it. This will create the widget bundle, and the folder icon will change to a widget icon. At this point widget is ready to be added to iBooks Author and on its way to iBooks app on your device. Don’t worry if you still don’t understand all the steps. We will cover all these steps in more details in the following subsections. Before that lets just analyze the structure of Info.plist file, which, based on our own experience, can cause some issues if not properly defined.
In previous section we have mentioned that Info.plist file is a textual file describing runtime execution of the HTML widget bundle. The file itself is encoded using the Unicode UTF-8 encoding and the content is structured using XML. The root XML node is a dictionary, whose elements are a set of keys and values describing different aspects of the widget bundle. The iBooks HTML execution engine uses these keys and values to obtain information about the widget and how it is configured. As any XML file, this file can have numerous keys (and corresponding values). Over time, Apple has standardized structure of these dictionaries for iOS and Mac apps, as well as for iBooks. For iBooks you should be concerned only with the following ten keys listed in the following table. In subsequent sections we will look into the example Info.plist files needed for our sample widgets to operate.
|Plist Keys for iBooks HTML Widget||Definition of the Key|
|Plist Keys for iBooks HTML Widget||Definition of the Key|
|CFBundleDevelopmentRegion||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||Required. A string that contains the actual name of the widget, to be displayed in iBooks Author and iBooks.|
|CFBundleIdentifier||Required. A string that uniquely identifies the widget, in reverse domain format.|
|CFBundleName||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||Optional. A string that gives the shortened version number of the widget. It is often the same as CFBundleVersion.|
|CFBundleVersion||Optional. A string that gives the version number of the widget.|
|MainHTML||Required. A string that gives the name of the HTML file that implements your widget.|
|Height||Optional. A number that gives the height, in pixels, of your widget. If not specified, the height of Default.png is used.|
|Width||Optional. A number that gives the width, in pixels, of your widget. If not specified, the width of Default.png is used.|
|IBNotifiesOnReady||Optional. When set to true, the widget tells iBooks when to switch from displaying the Default.png to displaying the running HTML widget.|
Slider Puzzle Game Example 1
In our first example we will start with the responsive HTML5 based slider puzzle game. You can download the code package from this link at Codecanyon web site. Once you download and unzip the archive read the documentation and copy the folder with fully responsive version of the app to a separate folder. That will be your starting point for making a widget based on downloaded files, which are nicely structured in css, img and js subfolders. You can test how it works in your desktop or tablet browser by loading the index.html file.
The following figure shows what kind of folder structure modifications you have to make.
Essentially, I have copied a content of original folder and renamed some of the subfolders as presented on the screenshot. I have replaced placeholder images with my own and I also created my own navigation buttons (left, right and preview). Finally, I have added Default.png widget cover image, as well as the Info.plist file. Structure of the Info.plist file is presented in the following figure.
<?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>slidingpuzzlewidget</string> <key>CFBundleIdentifier</key> <string>com.icandobetter.widget.slidingpuzzlewidget</string> <key>CFBundleName</key> <string>slidingpuzzlewidget</string> <key>CFBundleShortVersionString</key> <string>1.0</string> <key>CFBundleVersion</key> <string>1.0</string> <key>Height</key> <string>768</string> <key>MainHTML</key> <string>index.html</string> <key>Width</key> <string>1024</string> <key>IBNotifiesOnReady</key> <true/> </dict> </plist>
Before you finalize your HTML5 widget packaging, it is a good idea to test how everything works in your browser. I usually test it with iPad Safari browser emulator from within Safari. The following figure shows the initial HTML5 widget running in 3×3 puzzle mode.
This is the simplest mode where original image is divided into the 3×3 matrix. In the header you can see left/right arrows as well as the image preview button. If you click or tap on the preview button you will be presented with the puzzle solution image overlay. This can help the user (reader or player) to solve the puzzle. This is presented in the following figure.
If you click or tap on the right arrow, you are entering the next level – 4×4 puzzle matrix. In this case image is replaced with the next one to solve. This is presented in the following figure.
Now when we know that everything works fine it is time to package our widget. To do that you just have to rename the enclosing package folder by adding the .wdgt extension. When you do that, the icon of the folder will change into the widget icon.
It is time to add our newly packaged widget into the iBooks Author. Just create a new iBook and drag and drop *.wdgt file to the page. Your widget will be presented with your Default.png cover page.
If you click on it you can test the widget inside the iBooks Author.
Finally, preview your iBook on the device. Keep in mind that if you have upgraded to the new version of the iBooks Author, you will also need the latest iBooks app 3.x on your iPad. The following two screenshots are taken from the iPad running iBooks and presenting our test book with newly created HTML5 widgets.
Slider Puzzle Game Example 2
If you have downloaded the package you will have the folder structure as presented in the following figure. You can see that I have removed some of the options and added a CSS file for buttons.
You can proceed with the exact same procedure for testing the code on a desktop, renaming the folder into the HTML5 widget and testing in iBooks Author. The following images are taken from the iPad running the widget. You can see three buttons on the top of the image. The first one will initialize the widget by slicing the image in 3×3 matrix.
The second one will randomize the image pieces and at that point you can start solving the puzzle.
Finally, the third button gives you a hint on what the complete image looks like when puzzle is solved.
As an exercise you can extend the puzzle with additional images or you can try to use WebSockets and load images from the web.