Advanced iBooks Author HTML Widgets: Widget Events, Storing/Sending Data, and more

Widget Events when Opening / Closing Widgets

Using a Tumult Hype animation within a HTML Widget (in iBooks Author)
is very different from displaying it within a web page. Here are a few
things to consider when producing a widget:

  • When you play audio within a widget, it will keep playing even if the widget is closed.
  • You cannot pinch and drag on the widget. Pinching and dragging moves the widget area.
  • If you open a widget and go to a different scene, the document will
    remain right where you left if you close and reopen it. It will reset
    if the book is close, iBooks is closed (and shut down) or if the book
    has been closed for a certain amount of time.

To address some of these behaviors, Apple has exposed Widget
(also known as listeners) that are triggered when opening and
closing widgets. When exporting from Tumult Hype, AppleWidget.js is included in the head. The sample code included below can be added to the ‘head’ of your document to perform actions when closing or reopening
your widget:

    function myCallback(hypeDocument, element, event) {
    // Get the name of the document. This is also on line 5 of the generated javascript file. 
    window.DocumentName = hypeDocument.documentName();

    if("HYPE_eventListeners" in window === false) {
    window.HYPE_eventListeners = Array();
    window.HYPE_eventListeners.push({"type":"HypeDocumentLoad", "callback":myCallback});

<script type="text/javascript">
    widget.pauseAudioVisual = function() {
    // Go to the Quiet scene when closing a widget

    widget.didEnterWidgetMode = function() {
    // When reopening the widget, go back to the first scene

An example document can be downloaded here: (73.4 KB)

Updated June 9, 2016: Another demo document demonstrating when widget.pauseAudioVisual, widget.didEnterWidgetMode, and widget.willEnterWidgetMode trigger: (56.1 KB)

View this iBooks to see it in action: (1.0 MB)

Here’s an example book which contains a video showing how the ‘didEnterWidgetMode’ behaves as of May 12, 2016 in iBooks for iPad and iBooks for mac.

Override the Pinch Gesture

By default, the pinch gesture closes an open HTML Widget. To restrict
this behavior, add the following JavaScript in the head of your
document. You can edit the contents of the <head>...</head> of
your exported .html file by clicking on ‘Edit HTML Head’ in the
Document Inspector:

<script type="text/javascript"> 
  document.addEventListener('touchmove', function (e) {e.preventDefault();}, false);
  document.addEventListener('touchstart', function (e) {e.preventDefault();}, false);
  document.addEventListener('touchend', function (e) {e.preventDefault();}, false);

Pre-made Templates

Here’s a full screen template you can use for working around the X icon in the top left hand corner of the widget.

If you’re looking for more advanced widget creation tutorials, please check out this set of tutorials by Marielle Lange on Github. You’ll find code samples and documentation for widgets that
can store data that can be shared across widgets, widgets that can send data to a Google Form, and more. Another great resource is Jim McKeeth’s tutorials here.

Hi Daniel,

This was a very interesting post. I’m new to Hype and I don’t know anything about java script, but the sample code for “widget events opening and closing” may be what I’m looking for.

I’ve created a children’s book for iBooks using Hype to create the pages, which are exported as widgets. Each widget (page) has audio. In iBooks, if I swipe from one page to another before the audio from the previous page has stopped playing, the audio from the previous page will continue to play along with the audio of the current page. Since I know nothing about java, this code looks a bit intimidating. In iBooks, is it possible to have the audio of one widget (page) stop playing by selecting, in Hype, “On Scene Unload - Stop Sound”?

Hi Daniel and Jlam,

I’m also wondering if this code can be used to pause/stop audio from one widget when swiping to another Ibooks page containing another widget. It looks to me like this code only works when closing a widget (as opposed to swiping to another page) but any help would be appreciated.

For me audio is automatically stopped; perhaps you could provide a .hype and .iba file that reproduces it continuing to be played?

Regardless, I would expect this technique could be used to pause the audio. Step one would be to create a custom behavior that has actions to pause your audio. Then you’d probably modify pauseAudioVisual block to look like this to run the custom behavior:

widget.pauseAudioVisual = function() {

Thanks so much for your reply Jonathan.

i’ve created a simple example that I’ve uploaded to show what i’m talking about - an iba file and 2 hype docs .

I didn’t include your suggested code yet but it might be able to be triggered by the page 2 ‘play audio’ button effectively stopping the page 1 audio when you trigger the page 2 audio. Ideally the page 1 audio would stop automatically when you swipe across to page 2, but I don’t know if this is possible. (1.5 MB) (372.6 KB) (615.3 KB)

Ah, it appears the audio only plays through on macOS iBooks; iBooks on my iPad is what paused it.

The technique I described works - here’s page1 that will do the stopping of audio: (380.3 KB)

You’re totally correct - I test both on an iPad and macOS since I need to cater for both, but hadn’t noticed the audio only continues on macOS.

Your code in the head HTML combined with a custom pauseAudio behavior totally works - now audio automatically stops as soon as I swipe to another page in macOS - THANK YOU!

1 Like