Using the Dashcode HTML5 widget inside of iBooks Author

Using the Dashcode HTML5 widget inside of iBooks Author

23:22 28 January in iBooks Author


For the most part, I’ve found iBooks Author easy to use (simply drag in your Word Doc or insert a Keynote widget inside your book). However, there’s one thing I’ve found to be less straightforward than everything else: using the Dashcode html widget in iBooks Author.

At first, I thought it necessary to create something in Apple’s Dashcode application (which is not terribly easy to do), but I recently discovered that things are much simpler, and I’d like to share. At any rate, I hope this post will be helpful for those looking to do the same thing I was trying to do.

First, to create an HTML5 animation–just a simple one for testing. I’ll use Tumult Hype to create a simple HTML5 animation of a box moving from one side of the screen to the other. (If you need help with Hype refer to this post.)

Now this animation has to be exported as HTML5. Create a folder on your desktop into which you can export the file. (When we package this up for iBooks Author, we’ll need to have everything in a folder.)

Here’s the folder I created with the name HTML Sample. And I’ve named the exported HTML index. The reason for the name? To get this ready for iBooks Author, it’ll be necessary to create a p-list. (A p-list is something used in mobile programming which provides a list of all the files and information used in your app.) iBooks requires that your HTML and all the files with it be packaged up into a widget (extension: .wdgt). I’ll be going over how to do that in just a second.

Now that I’ve exported my HTML (index.html) to my newly created folder, I’m ready for the next step. iBooks requires two files. The first is the p-list I just mentioned. It’s an xml file required for any kind of iPhone or iPad development. I found a good example you can use (see the link below this paragraph). The second file you need to have in the folder is a PNG file called Default.png. From what I’ve been able to tell, there’s no size requirements (but keep in mind that it won’t take up the full iBooks page, so plan accordingly). You can easily make this yourself by taking a screen shot of your HTML5 animation when you preview it in your browser. (Just press Command + Shift + 4 to take a screen shot.) Or you can download a sample along with a p-list at the following link:

Download Sample info.plist and Default.png here.

Alright. Now you should have four things in your folder:

  1. index.html  (produced from Hype)
  2. index_Resources  (also produced from Hype–it has all your HTML5 resources)
  3. info.plist (downloaded from the link above–make sure you unzip it!)
  4. Default.png (created by taking a screen shot of your index.html file or downloaded from the link above)

Now it’s time to rename your folder. This may seem an unnecessary (or downright weird) step, but to bring HTML into iBooks Author it needs to be a .wdgt extension–and that’s what we’re going to make happen in renaming the folder. So we add .wdgt to the end of the folder (which, you’ll remember, I called HTML Sample). I slowly double-click the name of  my folder on my desktop, as if I meant to rename my folder, but instead of changing the name, I’m just going to add a .wdgt at the end of HTML Sample, and I get HTML Sample.wdgt.

As soon as I hit enter, I’m asked whether I want to add that extension onto the folder. The answer, of course, is yes, so I click Add.

Now take a look: the folder has changed icons:

That’s exactly what we’re after, since now can enter the widget into iBooks. Naturally, the next step is to pull up iBooks and insert the HTML widget onto a page:

Now, with the widget in your page, move it to where you want it (and make other necessary adjustments).

Next, pull up your inspector and make sure you’re on the last tab, widget settings.

Select the HTML widget on your page (if you don’t have it selected already). You’ll see you can now click the Choose button on the settings. This will pull up the file browser, and you can now find the widget you created: HTML Sample.wdgt. Select it and hit Insert.

And that’s it! You now have the HTML widget working inside your iBook. Preview it on your iPad, and it’ll play perfectly inside your book.

Watch the video below:

Be Sociable, Share!

Jeff Batt
  • Chris Brandt 17:06h, 07 February Reply

    Thanks for this — great start on how to NOT to HAVE to use Dashcode for authoring!


  • Thomas Gormley 19:04h, 07 February Reply

    Thank you!!

    You might want to add your blog address to the video’s page on you tube (or even to the video itself). I had a hard time finding your blog to download the files you mentioned in the video.

    • admin 19:21h, 07 February Reply

      Thanks for the advice. I updated my YouTube video to have my blog URL. Thanks!

  • Great tutorial! (but) 13:58h, 10 February Reply

    Hi, the ‘index.html’ file and the ‘resources’ link are not available to download at this page 🙁

  • Juan 12:23h, 11 February Reply

    Hi there, thanks for the tutorial, this one works great, but i wanted to go a little bit fowar using a video instead of pic, but it does not work, could you let me know hot to do it.


  • Juan 09:45h, 24 February Reply

    Thanks! I thought making those widgets was going to become a big headache. Your solution is as simple as amazing. I never would have thought of adding the extension!!!!
    Thanks again!!!

  • Rana Issa 13:56h, 08 March Reply

    I am trying to follow what you have done. The only difference I have done is that my HTML file is simple! It has “Hello Rana!” as content and that is it. I tried to enter it to iBook Author. When I do so, it gives me the following error:
    “The HTML Dashcode file “widget-test.wdgt” wasn’t added. The file is missing its main HTML” file, although I have had the Main HTML as index.html as the html file name…. do you know what could be the problem? I could send you the sample widget I created.

    Many thanks

    • luca troisi 16:20h, 29 May Reply

      Dear Rana

      did you find the problem and the solution? I’m experiencing the same

      • Marcos 01:57h, 26 March Reply

        I have the same issue!!

        • val 07:45h, 08 October Reply

          I have exactly the same problem of missing main HTML – did anyone manage to solve this?

          • Jeff Batt 07:52h, 08 October

            I have asked a couple of people to send me the files they have that are not working but no body has done that yet. Please email me at and I would be happy to take a look at what is not working.

  • Bruno Oliveira 19:13h, 19 March Reply

    very good!

  • Rahu 15:16h, 23 May Reply

    i made a widget for putting weblinks and opened the webpage in the same work.
    but i cann’t come back on the links ,i tried to close widget and reopened it bt it open on same web how can i close that browser page?

    • admin 22:40h, 23 May Reply

      So you made an HTML widget and when you preview it on your iPad and click on the links it does not let you go back to your iBook? It may be opening up safari which in that case you have to switch back to iBooks to go back if it is not opening up safari then it should still have the exit button.

  • Steve Wins 15:35h, 10 June Reply

    Thank you so much for this lesson. I have been trying to make this for a long time. I didn’t have a clue until I read your article. Thank you so much!

  • Jeff 13:47h, 14 June Reply

    Wow this is more difficult than it has to be haha.

  • Luciano Santos 20:48h, 23 June Reply

    Hello, I’ve created an animation with Hype and exported it as HTML5 to a iBook Author. But the widget into iBook only run in a full-screen. How can this HTLM5 run into the widget?

    • admin 03:12h, 24 June Reply

      The HTML widget will only play in full screen. In the regular window it just shows an image or a screen shot of the interaction so there is no way to not play it in full screen.

  • Jef Feldman 23:37h, 24 June Reply

    Thanks for the great tutorial on making iBooks widgets.

    Unfortunately, I can’t use Hype because it doesn’t support sound files in the timeline.

    I didn’t understand the plist, including which lines I would have to change. I plan to make my animations in Flash and then convert them to HTML5 using Swiffy. How would I have to change the plist in that case?

  • Jade 00:10h, 01 July Reply

    Hello! I did everything to a T, and I checked and double checked, but I’m having the same problem as Rana and Luca– the “The file is missing its main HTML” error when I try to put it into ibooks. When I type the .wdgt extension onto the folder, rather than turning into a widget icon it shows a blank page icon, like an error. What am I doing wrong?

    • admin 16:16h, 02 July Reply

      I am not sure what may be wrong without looking at your packaged files. Can you email that to me?

  • Egan2a 08:56h, 13 December Reply


    Thx a lot for this great tutorial. It works perfectly. I just have one question. Is it possible to had a sound with your method? I made my html 5 animation with edge animate with a sound. When I read the index.html, the sound works properly, but when I make the widget, it works without the sound in my iBook.

    I know edge animate alllows to make a widget, but there’s a bug, and I can’t export it successfully.

    Thx for the help!

    • admin 17:46h, 13 December Reply

      From what I have tested iBooks does not allow audio or video within your HTML widgets. I am hoping they allow this in future releases. I am not sure if anyone else has found a work around but that is what I know from my testing.

  • Ebi 18:31h, 29 January Reply

    Hype is good program for create widget for ibooks author.
    I used it and create mor widget for ibooks.
    You can use this link for more info.

    • admin 23:07h, 02 February Reply

      Thanks, I do show how to do this from Hype as well.

  • Geoff 07:48h, 18 April Reply

    First I wanted to thank you for giving me the inspiration and information on how to do this.

    I used your advice to take HTML5 created by converting an interactive Powerpoint file using the free version of HTML5POINT and convert it to a widget for an iBook.

    Now I don’t have to convert all my Powerpoint files to Keynote just to embed them!

    I was astonished to see it worked first time, even though I did not bother to change the sample info.plist file you provided 🙂

    Right now my slide seems to be a bit small as it plays (it plays full screen with a black border around it – I think I just need to tweak it a bit), but now that I know it works I will fool around with the parameters.

    There are a few other Powerpoint to HTML5 converters out there. Unfortunately they are all quite expensive. HTML5POINT is $99, and seems to be the cheapest so far.


Post A Comment