EPUB and WebGL

How It's Done

Creating an EPUB with embedded WebGL is relatively easy, once you have worked out a reasonable workflow. I am still working on refining the process, but the general workflow is as follows:

  • The EPUB was begun by creating the OPF, then adding the requisite HTML, CSS and scripts to the OPF and creating those files.
  • Editing of the OPF and other markup was done in Webstorm
  • WYSIWYG editing of the HTML text that forms the chapters was done in Dreamweaver. An "external tool" shortcut was added to Webstorm to facilitate jumping back and forth.
  • A little Java program was written (and invoked as a jar) that updates the OPF, setting the dcterms:modified to the current date and time. The source for the program is available on github.
  • A bash script was written to invoke that jar, zip up all the sources of the Webstorm project and then run them against EPUBCheck

The actual format of the EPUB is fairly straightforward. There are a few aspects that are worth noting. First, each chapter or lesson is actually two different spine items. The main part of the chapter is a reflowable spine item. The final page of each chapter is the actual functional WebGL demo. It is a separate spine item which is a fixed-layout page where the itemref in the spine has an override. Thus the second chapter's spine items are

<itemref idref="lesson02" />
<idref="lesson02-gl" properties="rendition:layout-pre-paginated"/>

It is done this way because the JavaScript code that is the demo has to have a specific size. Normally, in the browser the JS code fetches the size of the innerWindow, but that doesn't work from inside an EPUB reading system since it normally wraps the actual page content in a iFrame or other construct. So it works much better to specify a fixed size page.

The other interesting aspect is the use of PrismJS to colorize the JavaScript code for better readability. This requires that each block of code to be colorized be wrapped in a <code> element and the language specified as part a CSS style, e.g.

<code class="language-javascript">

Finally, all the illegal HTML characters need to be escaped (e.g. &lt; etc.). This is a bit of a pain since if the actual demo code is modified then the example code in the chapter has to be updated. Fortunately, most of the "code" is JavaScript (and not HTML) so it's pretty straightforward.


Click on this link to download an EPUB with a series of tutorials about using three.js and WebGL content
