Skip to main content

How to create different headers or footers on the first page of a document

Using Ibex you can create a document which has different headers and footers on different pages; that difference might be in the content of the header or footer or in its size and placement on the page.

This example shows how to create a document which different footer on the first page than all the other pages. The techniques shown here can be applied to the page header as well as the footer.

Approach​

We want to create a document where the first page is different to the other pages. The approach we take is to create two different simple-page-master elements, one to define the layout for the first page, and the other to define the layout for all other pages.

Defining page masters​

The simple-page-master for the first page looks like this:

<fo:simple-page-master master-name="first-page" page-width="8.5in" page-height="8in">
  <fo:region-body margin="3cm" region-name="body"/>
  <fo:region-after extent="2cm" region-name="first-page-footer"/>
</fo:simple-page-master>

This defines the geometry for a body region and a footer region named "first-page-footer".

The simple-page-master for all other pages looks like this:

<fo:simple-page-master master-name="other-page" page-width="8.5in" page-height="8in">
  <fo:region-body margin="3cm" region-name="body"/>
  <fo:region-after extent="2cm" region-name="other-page-footer"/>
</fo:simple-page-master>

This defines the geometry for a body region and a footer region named "other-page-footer".

Choosing a page master​

The two simple-page-master elements have different master-name attributes. We use this to distinguish between them. In addition to the two simple-page-master elements we need a page-sequence-master element; this controls the creation a sequence of pages. At the start of each page Ibex looks at the page-sequence-master element and determines which simple-page-master to use for that page.

The page-sequence-master for this example looks like this:

<fo:page-sequence-master master-name="pages">
  <fo:repeatable-page-master-alternatives>
    <fo:conditional-page-master-reference page-position="first" master-reference="first-page"/>
    <fo:conditional-page-master-reference master-reference="other-page"/>
  </fo:repeatable-page-master-alternatives>
</fo:page-sequence-master>

The page-sequence-master contains a repeatable-page-master-alternatives element, which contains a list of conditional-page-master-reference elements. At the start of each page, Ibex looks at this list and chooses one conditional-page-master-reference, which is then used to select which simple-page-master applies to that page.

On the first page, the condition [page-position="first"] is true, so that conidtional-page-master-reference is used, and the simple-page-master called "first-page" is selected.

On all other pages the condition [page-position="first"] is false, and the second conditional-page-master-reference is used, so the simple-page-master called "other-page" is selected.

It is important to realise that the order of the conditional-page-master-reference elements is crucial. At the start of each page Ibex looks at each conditional-page-master-reference in turn until it finds one for which the conditions are true. At that point the searching stops and other conditional-page-master-reference elements are not considered.

A common error is to do this:

<fo:page-sequence-master master-name="pages">
  <fo:repeatable-page-master-alternatives>
    <fo:conditional-page-master-reference master-reference="other-page"/>
    <fo:conditional-page-master-reference page-position="first" master-reference="first-page"/>
  </fo:repeatable-page-master-alternatives>
</fo:page-sequence-master>

In the FO above the first conditional-page-master-reference has no conditional attributes (such as page-position), so it will always be selected. In this document all the pages will have the same layout. Associating the flow with page masters

The page-sequence element should have its master-reference attribute set to the master-name of the page-sequence-master, not the names of any of the simple-page-master elements. Creating footer content

The page-sequence element should contain static-content elements for both types of page, the first page and the other pages. So the page-sequence looks like this:

<fo:page-sequence master-reference="pages">

  <fo:static-content flow-name="first-page-footer">
    <fo:block>
      page <fo:page-number/>
    </fo:block>
    <fo:block>this is the first page footer</fo:block>
  </fo:static-content>

  <fo:static-content flow-name="other-page-footer">
    <fo:block>
      page <fo:page-number/>
    </fo:block>
    <fo:block>this is the other page footer</fo:block>
  </fo:static-content>

  <fo:flow flow-name="xsl-region-body">

   <fo:block>
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. 
   </fo:block>

At the start of each page Ibex identifies which simple-page-master will be used on that page by evaluating the page-sequence-master element. Having identified which simple-page-master is used, Ibex now knows what regions will appear on that page.

On the first page the applicable simple-page-master is the one with master-name="first-page", so the regions on the page are named "body" and "first-page-footer".

On the second and all subsequent pages the applicable simple-page-master is the one with master-name="other-page", so the regions on the page are named "body" and "other-page-footer".

Having found the list of region names for that page, Ibex finds any flow or static-content elements whose flow-name attribute matches one of the regions on the page and renders the content of those flows. static-content elements whose flow-name does not match one of the regions on the page are ignored.