Understanding Apple’s fixed-layout EPUBs

by Liza Daly

iBooks now supports an extension to EPUB that allows publishers to create books with precise layout using CSS. This is Apple’s own extension, not part of the EPUB specification itself (and not one that they suggested be included in EPUB3).

The goal of this post is to simply document the extension and show how to create new works with it. I’m not going to debate whether it’s a good thing for the ecosystem here.

Install Phone Disk

Anyone working extensively with iBooks EPUB development should first grab a copy of the invaluable Phone Disk. This allows Mac and Windows computers to browse most of the iOS device filesystem as a normal drive, including opening and inspecting EPUB books.

Download a fixed-layout EPUB sample from the iBookstore

iBooks samples do not have DRM and so can be opened and read normally. A good bet is to download one of the “Children’s Picture Books”; these tend to be fixed-layout books.

Find the display-options file

The key component of the extension is the addition of the file META-INF/com.apple.ibooks.display-options.xml. This file tells iBooks that the book is the fixed-layout type, and typically looks something like this:

<?xml version="1.0" encoding="UTF-8"?>
<display_options>
    <platform name="*">
        <option name="fixed-layout">true</option>
    </platform>
</display_options>

There are a number of options here which are detailed in the iBookstore Asset Guide (v4.5), including how to define two-page spreads.

The first thing I tried with one of the samples was to validate it with the latest epubcheck 1.1:

Epubcheck Version 1.1
WARNING: /Users/liza/foo.epub: item (iTunesMetadata.plist) exists in the zip file, but is not declared in the OPF file
WARNING: /Users/liza/foo.epub: item (iTunesArtwork) exists in the zip file, but is not declared in the OPF file

These are just warnings; the fixed-layout book is valid. You can try opening them in other EPUB readers, with varying success depending on how wild the book designer got with the fixed-positioning.

Inspect the OPF and NCX

One immediate surprise to iBooks developers is that you’re likely to find an embedded font (now supported in any iBooks EPUB). Otherwise there’s nothing added to the OPF.

The NCX examples I found did not include all of the XHTML pages; I’m not sure whether that’s just a function of the book being a sample.

Structure of a fixed-layout book

In a typical EPUB, each chapter or major division of content is a single XHTML file. In the fixed-layout model, each XHTML file corresponds to a single physical page. So while it’s typical to name most EPUB XHTML files like chapter01.html, chapter02.html, in the fixed-layout book you’re apt to see a layout like:

cover.xhtml	font		package.opf	page001.xhtml	page003.xhtml	toc.ncx
css		images		page000.xhtml	page002.xhtml	page004.xhtml

XHTML content

The one unusual element in the fixed-layout content will be this HTML, which is required:

<meta name="viewport" content="width=1000, height=1000"></meta>

The specific width/height is per-book and based on the desired dimensions of the page. iBooks uses this information to scale the screen size appropriately (more on this later).

Otherwise the XHTML should look relatively normal (other than being very short). In fact the XHTML will be exceptionally readable since these books are by necessity all hand-coded at the moment.

CSS

Here’s where things get interesting:

The body element must be defined with an absolute width/height that matches the viewport above:

body {
	width: 1000px;
	height: 1000px;
}

Images and text will often be absolutely-positioned. z-index and other advanced positioning techniques are also supported. Font sizes are specified in pixels, not ems (users can zoom fixed-layout books, but the text will not reflow). Background colors are useful in this model as the XHTML content is full-bleed and does not usually have the goofy fake book margin.

Since this is all standard CSS 2.1 (or CSS3), these books don’t technically require a specialized reading system; any one based on a modern browser, like the mobile version of Ibis Reader, could potentially consume these books if the reading system could scale the pages appropriately.

Interactivity

It’s been noted that my original JavaScript in EPUB example no longer works in more recent versions of iBooks. This had nothing to do with the JavaScript parts themselves; instead the problem was that Apple began squashing the positioning information needed to align the popups.

In recent work for publishers I’ve found ways to get around those limitations, but they’ve been quite awkward and difficult to author. Would the “freedoms” of positioning in the fixed-layout books allow the original sample to work again?

Yes!

I took my original file and made only three changes:

  1. I added the com.apple.ibooks.display-options.xml file just as shown above.
  2. I added the viewport directive to the XHTML file and set it (arbitrarily to 600 pixels wide, 800 pixels tall).
  3. I modified the CSS body directive to match the viewport.

The result:

Download the example EPUB (Creative Commons Attribution-Noncommercial-Share Alike 3.0)

Obviously the layout could use some work; there’s no longer any default margin added by the ereader, so the text bleeds out. Also my 600×800 dimensions don’t exactly match the iBooks aspect ratio, so there’s more fake book border. But you can see how this could be improved.

Note that the vast majority of EPUB books should not be formatted this way. This isn’t a one-way ticket to CSS Town. If the text on a particular XHTML page overflows the bottom of the single page, it will get cut off. You cannot mix fixed-layout and reflowable pages in the same EPUB file.