Page Headers and Footers

Edit online

The headers and footers are part of the page definitions. To see how the default page layouts are defined, see: Default Page Definitions.

To change the font for all the headers and footers, in your customization CSS add a CSS rule similar to this:

@page {
    font-size: 12pt;
    font-family: "Arial";
}

If you want to change the settings only for a specific page type (for example, the table of contents), use the name of the page:

@page table-of-contents {
    font-size: 12pt;
    font-family: "Arial";
}

© 2017 - My Company Ltd
All rights reserved

For this, you need to specify a rule that matches all the right pages and adds that content in the bottom-center. In your customization CSS, add the following CSS rule:

@page :right{
    @bottom-center {
        content: "© 2017 - My Company Ltd \A All rights reserved";
        font-size: 0.5em;
        color: silver;
    }    
}

@page :right, table-of-contents:right {
  ...
}

To create a footer that contains the content of several topic files, but only on the last page, there are two possible approaches:

*[outputclass ~= "footer"] {
  float:footnote;
}

*[outputclass ~= "footer"]:footnote-call{
  color:transparent;  
  font-size:0;
}

*[outputclass ~= "footer"]:footnote-marker{
  color:transparent;  
  font-size:0;
}

A common use-case is to add a background image to one of the page corners.

@page :left {
    @bottom-left-corner{
        content: " ";
        background-image: url('https://www.oxygenxml.com/resellers/resources/OxygenXMLEditor_icon.svg');
        background-repeat:no-repeat;
        background-position:50% 50%;        
    }
}

Another use-case is to use one of the @top-left or @top-right page margin boxes. These boxes have an automatic layout and they can be very small if they have no content. If there is no text to be placed over the image, use a series of non-breaking spaces (\A0) to increase the box width as in the following example (alternatively, you can use the technique described in How to Decorate the Header by Using a Background Image on the Entire Page):

@page :left {
    @top-left{
        content: '\A0\A0\A0\A0\A0\A0\A0\A0\A0\A0';
        background-image: url('https://www.oxygenxml.com/resellers/resources/OxygenXMLEditor_icon.svg');
        background-repeat:no-repeat;
        background-position:50% 50%;
    }
}

If you want to precisely position artwork and the page margin boxes are not sufficient, it is possible to use a background image for the entire page.

This technique consists of creating an image (SVG is the best since it is a vector image) as wide as the page that would contain the logo and placing other decorations at the desired locations. This offers the best results and the position of the artwork does not depend on the page margin contents.

Example:

@page :left, chapter:left, chapter:first:left { 
 background-image: url('img/page_background_image_with_logos_and_artwork_for_left_page.svg');
 background-repeat: no-repeat;
 background-position: 50% 50%;
}

For a list of all the possible page names, see: Default Page Definitions.

The headers display information such as map title, part title, chapter title, and section title, ending in the page number.

content: string(maptitle) string(parttitle) string(chaptertitle) string(sectiontitle) " | " counter(page);

This might be too much if you have long titles. The solution is to override the default header content.

In your customization CSS, add the following CSS rule:

@page :left {
    @top-left {
        content: string(chaptertitle) " | " counter(page);
    }
}
@page :right{
    @top-right {
        content: string(chaptertitle) " | " counter(page);
    }
}

@page :left, table-of-contents:left, chapter:left{
  ...
}
@page :right, table-of-contents:right, chapter:right{
  ...
}

My Publication | Introduction | Getting Started 

There might be cases where you want to change this separator. You will need to recompose the header content using the above string sets. Suppose you want to use " - " as a separator. In your customization CSS, add the following CSS rule:

*[class ~= "topic/topic"][is-part] > *[class ~= "topic/title"] {
    string-set: parttitle " - " counter(part, upper-roman) " - " content(), chaptertitle  ""; /* Avoid propagating a past chapter title on a new part */
}
*[class ~= "topic/topic"][is-chapter]:not([is-part]) > *[class ~= "topic/title"] {
    string-set: chaptertitle " - " counter(chapter) " - " content();
}

If you enabled the Deep Numbering - Built-in CSS, then use:

/* 
 * Alter the string sets that are shown in the header of the page.
 */
*[class ~= "topic/topic"][is-part] > *[class ~= "topic/title"] {
    string-set: parttitle " - " counter(part, upper-roman) " - " content(), chaptertitle  ""; /* Avoid propagating a past chapter title on a new part */
}
*[class ~= "topic/topic"][is-chapter]:not([is-part]) > *[class ~= "topic/title"] {
    string-set: chaptertitle " - " counter(chapter) " - " content(), sectiontitle "";
}
*[class ~= "topic/topic"][is-chapter]:not([is-part]) > *[class ~= "topic/topic"] > *[class ~= "topic/title"] {
    string-set: sectiontitle " - " counter(chapter) "." counter(section1) " - " content();
}

To modify the styling of the default page headers, add the following CSS rule in your customization CSS:

@page :left {
    @top-left {
        color:navy;
        font-style:italic;
    }
    @top-right {
        color:red;
    }
}

If you intend to modify just the headers of the table of contents, use the table-of-contents page rule selector:

@page table-of-contents:left {
    @top-left {
        color:navy;
        font-style:italic;
    }
    @top-right {
        color:red;
    }
}

A very simple approach is to use the oxy_xpath directly in the content property:

@page front-page {    	
     @top-center {
          content: "Created: " oxy_xpath('//*[contains(@class, " topic/created "][1]');
     }
}

Example 1: Compute the Number of Words

The following example computes the number of words from the publication. It counts all the words, including the ones from the TOC, but does not take the static labels into account:

@page front-page {
     @bottom-center {
          content: "Number of words: " 
                    oxy_xpath("string-length(normalize-space(/)) - \
                               string-length(translate(normalize-space(/),' ','')) +1");
     }
}

Example 2: Retrieve Image from a Document and Insert it in the Header

<bookmeta>
  <metadata>
   ...
    <data name="cover">
        <image href="product-cover.png" outputclass="cover-image"/>
    </data>
   ...
  </metadata>
</bookmeta>

@page {
   @top-center {
        content: url("oxy_xpath('//*[contains(@outputclass, "cover-image")]/@href')");
   }
}

If the URL returned by oxy_xpath is not absolute, it is considered to be relative to the CSS file. To obtain an absolute URL from one relative to the XML document, you can use in the XPath expression functions like resolve-uri and document-uri:

@page {
   @top-center {
        content: url(oxy_xpath("resolve-uri(//*[contains(@outputclass, 'cover-image')]/@href), document-uri(/))"));
   }
}

Example 3: Insert the Current Date in the Footer

Another example is to use the oxy_xpath function to compute the current date and insert it in the publication footer:

@page {
    @bottom-left {
        content: oxy_xpath('current-date()');
    }
}

It is possible to dynamically change an image in the header depending on the chapter. For this, you need to define an image reference in the metadata section of each chapter. One way is to specify it in the DITA map by using the <topicmeta> element for the <chapter> topic reference:

...
 <chapter href="topics/installing.dita">
    <topicmeta>
      <data name="header-image" value="img/installing.png"/>
    </topicmeta>
    ...

In the above example, there is set of key value pairs with the name header-image. The img/installing.png is an image reference relative to the DITA map URI. This information is automatically copied into the content in the merged map file, like this:

<topic is-chapter="true" ... >
    <title class="- topic/title ">Installing</title>
    <shortdesc class="- topic/shortdesc ">You install components to make them available for your
      solution.</shortdesc>
    <prolog class="- topic/prolog ">
      ...
      <data class="- topic/data " name="header-image" value="img/installing.png"/>
      ...

This information can be picked up from CSS:

/* Define the string set variable that contains an URL */
*[class ~= "topic/topic"] *[class ~= "topic/data"][name="header-image"] {
  string-set: imgst oxy_url(oxy_xpath('/*/@xtrf'), attr(value));
}

/* Using the value='none' stops applying the image. */
*[class ~= "topic/topic"] *[class ~= "topic/data"][name="header-image"][value="none"] {
  string-set: imgst "";
}

/* Use the string set variable in one of the page margin boxes. */
@page chapter {  
  @top-left-corner {
    content: string(imgst);
    font-size:0; /* remove the font ascent and descent */
  }
}

Details: The @value attribute is used to build a URL relative to the URI of the DITA map. To determine the base URI of the DITA map, the @xtrf attribute was used from the root element of the merged map document, extracted using the oxy_xpath function.

There are two ways to add a horizontal line under the header.

@page chapter, chapter:first:left:right, front-page{

   padding-top: 1em;
 
  @top-left {
    content: "Custom header";
    color: gray;
    border-bottom: 1px solid black;
    vertical-align: bottom;
  }

  @top-center{
    content:" ";
    border-bottom: 1px solid black;
    vertical-align: bottom;
  }

  @top-right{
    content:" ";
    border-bottom: 1px solid black;
    vertical-align: bottom;
  }

  @top-right-corner{
    content:" ";
    border-bottom: 1px solid black;
    vertical-align: bottom;
  }

  @top-left-corner{
    content:" ";
    border-bottom: 1px solid black;
    vertical-align: bottom;
  }