Page Headers and Footers

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

This is directly related to the page margins and size.

The headers and footers are placed in the so-called page margin boxes, a series of rectangular areas residing in the page margins.

To affect the margins of all page definitions, you may use the following rule:

@page {
	margin-top:3cm !important;
	margin-bottom:3cm !important;
	margin-left:2cm !important;
	margin-right:2cm !important;	
}

If you want to affect only a specific page, like the first page from chapters for instance, you must use more specific page selectors. See the Default Page Definitions for details.

Note that the page margin boxes fill the entire page margin. This means the margin-top, for example, dictates the height of the @top-left-corner, @top-left, @top-center, @top-right, @top-right-corner margin boxes. These cannot have margins on themselves, so to change the position of the content inside them, you must use padding properties:

@page {
	@top-left {
		content:"..."
		padding: 1cm;
	}
	..
}

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";
}

By default, the name of the publication and chapter titles are placed in the top-left or top-right page margin boxes:

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

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

If you want to change this, you should use the content CSS properties of other page margin boxes, and inhibit the ones in the above content. For example, to set the chapter title in the page top left corner, you can use:

@page :left {
  @top-left {
    content: string(maptitle) string(parttitle) string(chaptertitle) string(sectiontitle) " | " counter(page);
  }
  @top-left-corner {
    content: string(maptitle) string(parttitle) string(chaptertitle) string(sectiontitle) " | " counter(page);
    white-space: nowrap;
    text-align:left;
  }
}

@page :right{
  @top-right {
    content: string(maptitle) string(parttitle) string(chaptertitle) string(sectiontitle) " | " counter(page);
  }
  @top-right-corner {
    content: string(maptitle) string(parttitle) string(chaptertitle) string(sectiontitle) " | " counter(page);
    white-space: nowrap;
    text-align: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(), 
              parttitle-no-prefix " " counter(part, upper-roman) " - " content(), 
              chaptertitle "", 
              chaptertitle-no-prefix ""; /* 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(), 
              chaptertitle-no-prefix " " counter(chapter) " - " content();
}

If you enabled the deep numbering for chapters and subsections, then use:

*[class ~= "map/map"][numbering ^= 'deep'] *[class ~= "topic/topic"][is-part] > *[class ~= "topic/title"] {
  string-set: parttitle " - " counter(part, upper-roman) " - " content(), 
              parttitle-no-prefix " " counter(part, upper-roman) " - " content(), 
              chaptertitle "", 
              chaptertitle-no-prefix ""; /* Avoid propagating a past chapter title on a new part */
}
*[class ~= "map/map"][numbering ^= 'deep'] *[class ~= "topic/topic"][is-chapter]:not([is-part]) > *[class ~= "topic/title"] {
  string-set: chaptertitle " - " counters(chapter-and-sections, ".") " - " content(), 
              chaptertitle-no-prefix " " counters(chapter-and-sections, ".") " - " content(), 
              sectiontitle ""; /* Avoid propagating a past section title on a new chapter */
}
*[class ~= "map/map"][numbering ^= 'deep'] *[class ~= "topic/topic"][is-chapter]:not([is-part]) > *[class ~= "topic/topic"] > *[class ~= "topic/title"] {
  string-set: sectiontitle " - " counters(chapter-and-sections, ".") " - " content();
}

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);
    }
}

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 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%;
  background-size: 8.5in 11.5in; /* Optional: Adapt to your page size. */
}

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

It is possible to dynamically change the header depending on the content in a topic. The following example assumes that the data to be presented in the header is located in the metadata section of each topic. One way is to specify it in the DITA map is by using the <topicmeta> element for the <topicref> topic reference:

...
 <topicref href="topics/installing.dita">
    <topicmeta>
      <data name="header-data" value="ID778-3211"/>
    </topicmeta>
    ...

In the above example, there is set of key value pairs with the name header-data. This information is automatically copied into the content in the merged map file, like this:

<topic ... >
    <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-data" value="ID778-3211"/>
      ...

This information can be extracted from the CSS:

/* Define the string set variable that contains the text extracted from the data element */
*[class ~= "topic/topic"] *[class ~= "topic/data"][name="header-data"] {
  string-set: hdrstr attr(value);
}

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

/* Use the string set variable in one of the page margin boxes. */
@page chapter {  
  @top-left-corner {
    content: string(hdrstr);
  }
}

...
 <topicref href="topics/installing.dita">
    <topicmeta>
      <data name="header-data" value="ID778-3211"/>
    </topicmeta>
 </topicref>
 <topicref href="..."> <!-- Uses the same value -->
 <topicref href="..."> <!-- Uses the same value -->
 <topicref href="..."> <!-- Uses the same value -->
 <topicref href="topics/change.dita">
    <topicmeta>
      <data name="header-data" value="ID990-3200"/>
    </topicmeta>
 </topicref>
 <topicref href="..."> <!-- The string set is changed now -->
 <topicref href="..."> <!-- The string set is changed now -->
 <topicref href="..."> <!-- The string set is changed now -->

...
     <topicref href="..."> <!-- The string set is void now -->

...

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.

© 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;
}

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]');
     }
}

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

<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')");
   }
}

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

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

:root{
        string-set: maptitle oxy_xpath('document(@xtrf)/*[contains(@class, " map/map ")]/*[contains(@class, " topic/title ")]/text()');
}

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;
  }

Suppose you need to change the headings of your publication by specifying a static text in a parameter.

First, establish a name for your parameter (it must start with the args.css.param. prefix). For example, you could name it args.css.param.heading.text. It will have the text value that you will pass when starting the transformation. This parameter does not have to be registered anywhere as it will be automatically recognized and passed as an XML attribute on the root of the merged file, as specified in Styling Through Custom Parameters.

Next, alter your customization CSS to make use of the parameter value. In the example below, the text is placed in the central part of the header:

@page front-page, table-of-contents, chapter {
    @top-center{
        content: oxy_xpath("/*/@heading.text");
    }    
}

The text does not affect the first pages from the page sequences because the built-in CSS page rules clear the content from the headers. If you need the text content on all pages, you might consider adding an !important keyword after the content property value, or increase the specificity of the page selectors, like this:

@page front-page, 
      table-of-contents, 
      table-of-contents:first:left, 
      table-of-contents:first:right, 
      chapter:first:left, 
      chapter:first:right{
    @top-center{
        ...
    }    
}

Another use case is to alter the string-sets that are used in the headers (not the headers directly), as it is explained here: How to Use XPath Computed Data or Images in the Header or Footer. You can use this technique to alter the chapter titles as in the following example:

*[class ~= "map/map"][numbering^='deep'] 
   *[class ~= "topic/topic"][is-chapter]:not([is-part]) > 
        *[class ~= "topic/title"] {
    string-set: 
            chaptertitle " | " counters(chapter-and-sections, "." ) " - " oxy_xpath("/*/@heading.text") content(), 
            sectiontitle "";
}

It is possible to customize the text displayed in the headings depending on the language of the publication.

In this case, you can simply use of the @lang attribute in your customization CSS. In the following example, the page counter displayed in the bottom part of the page is preceded by the word "Page", according to the selected language:

@page chapter {
  @bottom-center {
    content: oxy_xpath("if (@lang='es') then  'Página' \
                        else if (@lang='it') then 'Pagina' \
                        else 'Page'") " " counter(page);
  }
}