Embedding within the Baker Framework: Ebooks for the iPad

We take requests!

The Baker framework is a powerful ebook framework that builds a complete iOS app or News Stand (also iOS) publication based on HTML documents. Adding Tumult Hype documents within these HTML pages is a wicked easy way to add interactive elements to your Baker publications. The Baker Framework is meant for publications that consist of mostly text, but there’s nothing stopping you from making a series of Tumult Hype animations that your users can swipe between.

Below are a few key ideas to keep in mind and tips as you build Tumult Hype documents into your Baker publication.

Structuring your document

Firstly, A great way to introduce yourself to the framework is to download the example book at http://bakerframework.com/ called ‘HPub example’ & to check out what others have done.

The Baker framework uses a swipe from right to left system to advance from one .html file to the next. Because of this behavior, swiping on a Hype element will be intercepted. Since swipe gestures are overridden, use other types of interactivity so as not to confuse or limit your users.

To use Swipe actions anyway, you’ll need to place your Tumult Hype documents within an iframe, as opposed to the standard div method.

Tweaking book.json

A wide array of document settings are stored in the ‘book.json.’ file. All the settings and explanation for this file can be found on this page: http://bakerframework.com/tutorials/30/manifest. When considering the size of Hype documents you use, you’ll probably want to lock an orientation. This ensures that your users will always see your Hype document displayed in ‘Landscape’ or ‘Portrait’. Likewise, you’ll probably want to set the ‘zoomable’ property to false so that users don’t accidentally zoom into your pages. For 'baker-specific properties, use -baker-rendering": “three-cards”. This, we’ve discovered boosts performance.

If you use the ‘three-cards’ rendering option, Hype content one page ahead of the reader’s current position will load so it is ready when that page is turned to. This is important to keep in mind if you have animations playing ‘on scene load’ or audio that auto plays. For more information on setting the rendering option, please see this page.

Detecting Baker Framework Events

Two events may be useful for your Tumult Hype animations: Focus: This event can be used to start your Tumult Hype animation. If you run this JavaScript ‘on scene load’ for your first scene, it can be used to start your animation at the correct moment:

window.addEventListener("focus", function() { 
     hypeDocument.startTimelineNamed('FocusTimeline'); 
     // or, start a scene! 
     // hypeDocument.showSceneNamed('myfirstscene', hypeDocument.kSceneTransitionInstant) 
     }, true);

The ‘Blur’ event can be run to detect when your animation no longer displays. This is highly recommended for boosting the performance of your book. Otherwise, your animation will continue to play if you have any looped timelines. This JavaScript can also be run ‘On Scene Load’:

window.addEventListener("blur", function() { 
        hypeDocument.pauseTimelineNamed('Main Timeline');
        // or, redirect to a scene with no animations:
        // hypeDocument.showSceneNamed('myquietscene', hypeDocument.kSceneTransitionInstant) 
 }, true); 

A demo document is available at the bottom of this article. Please see the ‘Part1-01.html’ file to see how the file was added to the book. The document was exported to the ‘gfx’ folder. Please note that there’s no need to include the exported .html file in your book unless you’re embedding an iframe for some reason, but we’ve left it in.

The book folder

There’s a few things to keep in mind when exporting Tumult Hype documents to the ‘book’ folder:

  • If you build your layout with the Portrait orientation in mind, you can restrict the book to not ‘rotate’ when the device is rotated. This is set in the ‘orientation’ value of the book.json file. That value can be “both”, “portrait”, or “landscape”. If you choose both, I would ensure that text is a good minimum reading size in the ‘Portrait’ version, since it will be enlarged in the ‘Landscape’ version.
  • Since you’re likely targeting the iPad (Baker supports both iPad and iPhone), use an iPad-friendly document size. If your document is meant for the Portrait orientation, then use the width ‘768’ – if you’re targeting Landscape, then 1024 should be your width. Because your ‘Chapters’ only need a defined width, you can set the height to whatever the length your text is. Since sometimes it’s hard to estimate this length, you can remove the “overflow:hidden” property from the exported documents you create.
  • If you’re working with videos, the only version you’ll need is the ‘mp4’ format. The optimum dimension for iPad video is 1024×768, encoded using the H.264 codec. Keep in mind that any movies added will increase the download size of the resulting app, unless you reference the video from a website. Of course, that would make the publication non functional if the user is offline.
  • If you’re linking from one Hype document (or, maybe it can be called a ‘chapter’ in Baker), you would just need to set an ‘On Click’ mouse action and include the name of the .html document as an URL (e.g. Story1.html). Linking functions the same within Baker as it does on the web when navigating between different pages on the same domain and on the same level.

Full-Page Magazine

To create a series of Tumult Hype documents that act as the entire pages of an Baker project, you’ll need to treat each Tumult Hype document as its own chapter, and define each chapter in the ‘contents’ section of book.json. Lock the orientation and turn ‘zoomable’ to off there as well.

Automatic Index file (index.html)

The framework automatically loads a file at the bottom of the screen called index.html (this can be made with Hype) when you double tap anywhere on the screen. The height of that area of the screen is set on this line:

"-baker-index-height": 202

… located in book.json. That value would produce an index that is 202 pixels high. That horizontal bar is useful for replicating the table of contents, or list of stories. Because of this feature, you would need to create a Hype document (or regular document) called index.html, which should also be stored in the /book/ folder.

Notes from @mprefit

  • Avoid interaction in the left or right 50px of the page. Baker reserves this area for page turning
  • Drag actions are not recommended, since these are also handled by Baker’s built-in page turning detection
  • You may need to stop your video when exiting your scene. Simply run document.getElementById('video1').pause(); ‘On Scene Unload’. Using an external video host? See this article.
  • Read this Baker article for help on linking within your book and to external resources.
  • Read more notes on Baker book preparation here.

Issues with Baker

You can track any issues with the Baker framework itself here, and feel free to send us an email with any problems you have.

Share!

Share your amazing books with us!

5 Likes

Excellent tutorial! I appreciate your efforts, there’s a huge potential bringing full interactivity to html magazines!

Also, here’s a list of partners that support hosting your magazine if you don’t want to host it on your own servers, or if you want to enable paid subscriptions and purchases:
http://www.bakerframework.com/partner-program/partner-directory/

1 Like