Page Templates in Adobe Digital Editions 1.0

Introduction to XPGT

Adobe Digital Editions viewer implements several layout extensions to ePub format. These include:

These extensions are typically used together and can be all packaged as an additional stylesheet, called XML Page Template (XPGT). It can be referenced like any other stylesheet directly from an XHTML file:

<html xmlns="http://www.w3.org/1999/xhtml">
<head>
...
<link rel="stylesheet"
   type="application/adobe-page-template+xml"
   href="template.xpgt"/>
</head>
<body>
...
</body>
</html>
Alternatively, XPGT file can be pulled in from a CSS stylesheet with import statement:
@import url(template.xpgt);
XPGT file should also be declared in the OPF manifest and assigned media type "application/adobe-page-template+xml". As you might have guessed from the media type, XPGT is using XML rather than CSS-like syntax. Here is how XPGT file is structured:
<ade:template xmlns="http://www.w3.org/1999/xhtml"
          xmlns:ade="http://ns.adobe.com/2006/ade"
		 xmlns:fo="http://www.w3.org/1999/XSL/Format">
 <fo:layout-master-set>
   <!-- list of page master definitions -->
   <!-- page master selection -->
 </fo:layout-master-set>
 <ade:style>
   <!-- dynamic styling rules -->
 </ade:style>
</ade:template>

Let’s go over the individual sections.

Page Master Definitions

This section contains one or more page master definitions (they are called simple page masters in XSL:FO). A page master defines a partitioning of the page’s surface space into a set of regions. Each region is an area which can be occupied by a flow. A flow is a sequence of flowable content – paragraphs, lists, images, tables, etc. A sample page master is shown below:

<fo:simple-page-master master-name="two_column_head">
  <fo:region-before extent="6em"/>
  <fo:region-body column-count="2" column-gap="10pt" 
	margin-bottom="1em" margin-top="6.2em"
      margin-left="0.3em" margin-right="0.3em"/>
</fo:simple-page-master>

The mark-up above defines a page master named “two_column_head” that splits the page into a 6em-high header region and a body region. The body region has two columns in it. There is 10pt gap between columns and there are margins around the body region. Note that each region is positioned independently in XSL:FO, therefore the top margin of the body region is enlarged to avoid an overlap with the header region. By default region names in the example above are “xsl-region-before” and “xsl-region-body”. Different names can be given using region-name attribute.

Page Master Selection

The next section specifies how to build a sequence of pages in the document using previously defined page masters (possibly different masters for different pages). Again, XSL:FO mark-up is used. Several extensions are available to achieve dynamic effects.

<fo:page-sequence-master>
  <fo:repeatable-page-master-alternatives>
    <fo:conditional-page-master-reference
       master-reference="two_column_head" page-position="first"
       ade:min-page-width="50em"/>
    <fo:conditional-page-master-reference
       master-reference="two_column"
       ade:min-page-width="50em"/>
    <fo:conditional-page-master-reference
       master-reference="single_column"/>
 </fo:repeatable-page-master-alternatives>
</fo:page-sequence-master>

The meaning of the above mark-up snippet is: “repeatedly choose the first acceptable page master from the list”. What is “acceptable” is determined by the conditions on the fo:conditional-page-master-reference element attributes. The attribute page-position=”first” specifies that this page master is only acceptable for the first page. The attribute ade:min-page-width specifies minimal acceptable width of the page for a page master. It is also possible to specify ade:condition attribute and place any general condition there as an XPath expression (in curly braces).

Dynamic Styling

The final section describes styling rules that depend on the environment (dynamic styling). These rules work together with rules CSS stylesheets. The rules in the page template have higher priority (specificity in CSS terms). Therefore CSS slylesheets should be used to specify environment-neutral styling of the document and page template styling should be used for environment-specific styling.

Just like CSS rules, page template styling rules have a selector which determines a set of applicable elements and a set of properties that the rule assigns to the elements. Selector is specified using selector attribute using regular CSS syntax. Properties are specified using attributes with matching names. In addition, styling rule can contain a condition which determines if the rule should be applied given a particular environment. Here is an example:

<ade:styling-rule selector=".ibox"
 condition="{ade:page-width() &gt; 22*ade:default-font-size()}"
 float="left" width="70%" margin-top="0pt"
 margin-right="0.5em" margin-bottom="0pt" margin-left="0pt"/>

This rule applies to all elements with class ”ibox”. It sets a number of properties (float, width, margins) of these elements. It is only applied when page width is greater than 22 times default font size.

Conditions are specified using XPath expressions in curly braces. Here is a list of XPath extension functions to query the environment:

ade:page-width()The width of the page in CSS pixels
ade:page-height()The height of the page in CSS pixels
ade:page-aspect()Page width divided by page height
ade:default-font-size()Default font size in CSS pixels
ade:device-is-color()True if the device supports color
ade:resolution()Size of the inch in CSS pixels

It is also possible to assign values of the properties based on the environment by specifying property value as an XPath expression in curly braces:

<ade:styling-rule selector=".top"
 condition="{ade:page-width() &lt; 36*ade:default-font-size()}"
 font-size="{ade:page-width() div 10}"/>

This styling rule assigns font size of the elements with class “top” to 1/10th of the page width when page width becomes less than 36 times default font size.

Assigning Content to Page Master Regions

By default all the content of an XHTML file goes into “xsl-region-body” region. It is possible to assign elements to different regions by specifying display and adobe-region properties. It should be done with page template styling (it is also possible to do with CSS, but since page template must be specified anyway, it makes sense to put all page-template related styling in page template itself).

<ade:styling-rule selector=".top" display="adobe-other-region"
     adobe-region="xsl-region-before"/>

“adobe-other-region” is a special value for display property that makes an element to display as a block in the different region. The region name is specified by the adobe-region property. If such region does not exist, an element is simply displayed as a block.

Epub Documents without Page Template

There are always going to be many documents that do not choose to incorporate a specific page template. Indeed it is a goal that documents that do not wish to declare custom intentions with respect to page layout should not need to incorporate such markup. Obviously, a Reading System that supports the page template extension must be able to process such documents.

One strategy would be to render such documents in a single column, no matter how large the viewing are is and how small the font size is. This would mean that such documents would look quite ugly. So if no page template is specified Adobe Digital Editions 1.0 automatically switches to 2 columns when width is about 61.5em and to three column layout when width is 93em. Column gap is about 1.5em. These numbers may change in future.

Relationship to oeb-* CSS properties

OPS 2.0 specifies its own extensions to CSS to set the number of columns in the form of oeb-prefixed properties. Currently Digital Editions does not support these properties, however our goal is eventually to support complete OPS 2.0 spec. Information in this section can provide some guidance for the future, but I should stress that things do change. This is my best guess for today

oeb-column-number can be used to specify the number of columns. Digital Editions 1.0 behaves as if the value auto was always specified on the XHTML body element. The major difference between oeb-column-number and page templates is that oeb-column-number can be used on any element, not only the body element. This makes it harder to implement efficiently. One drawabck of oeb-column-number is that it is not inherently dynamic and it is hard to imagine a layout which would use multiple columns of text no matter what the viewport width is. Unless some good use for this property is discovered, don't count on this being implemented soon (beyond treating any numerical value as 1).

oeb-page-head and oeb-page-head values for display properties can be used to move the content to the page header or footer area. They are very similar to adobe-other-region display value, but need dynamic allocation of the header and footer space - something that Digital Editions 1.0 still cannot do. In future they are expected to work just like adobe-other-region value with adobe-region set to either xsl-region-before or xsl-region-after - at least in paginated mode. The good thing about these properties is that they are convey more semantic than adobe-other-region and thus can be used by Digital Editions even if epub is displayed in scroll mode (something that we do not have currently). Thus, I think these values are critical to implement right.

Relationship to CSS3 features

CSS specification is evolving beyond CSS2.1 in the shape of multiple CSS3 modules. Several of CSS3 modules aim to the solve the same problems as page template: adding headers and footers, multi-column layout and dynamic styling. All of these modules are still being designed and cannot be relied upon. Since CSS group chose to ignore a lot of perevious work in this area (e.g. inventing its own expression syntax for media queries instead of using XPath, designing its own incompatible replacement of page master instead of building on top of XSL:FO), the amount of the implementation work that would be required to achieve parity even with Digital Editions 1.0 is huge. This does not preclude implementing CSS3 syntax for these features if they become stable and gain some acceptance, but it makes too expensive for us to experiment with them at this time.