Table of Contents
More Resources
Adding a Header
Header
Customize your PDF output by adding a specific header with a company logo, document title, and page number.
Editing a Header Template
Edit the custom-xsl.xsl file to add a header to your main content pages.
Adding Header Attributes
Define attribute-sets so that your header appears as expected.
Adding a Background Color
Add a background color to your header or footer.
Adjusting the Header Size
Adjust the size and alignment of your header.
Header

Customize your PDF output by adding a specific header with a company logo, document title, and page number.
section
You can add a custom header to your main content pages when publishing to PDF. Adding a header to your PDF output requires:
Important:If you use a custom variable while Editing a Header Template, you’ll also need to Setting Global Variables.
You can also customize your header by Adding a Background Color and Adjusting the Header Size.
Editing a Header Template

Edit the custom-xsl.xsl file to add a header to your main content pages.
context

You want to add a header template to the custom-xsl.xsl file (located in cfg/fo/xsl/) to add a header with an image, the document title, or multiple lines of text.

  1. To add a custom header, you need to modify the insertBodyOddHeader template. The default header in org.dita.pdf2 uses the Body odd header variable, which displays the product name, header content, and page number:

    Step Information
    < xsl:template name="insertBodyOddHeader"> 
      < fo:static-content flow-name="odd-body-header"> 
        < fo:block xsl:use-attribute-sets="__body__odd__header"> 
          < xsl:call-template name="insertVariable"> 
            < xsl:with-param name="theVariableID" select="'Body odd header'"/> 
            < xsl:with-param name="theParameters"> 
              < prodname> 
                < xsl:value-of select="$productName"/> 
              < /prodname> 
              < heading> 
                < fo:inline xsl:use-attribute-sets="__body__odd__header__heading"> 
                  < fo:retrieve-marker retrieve-class-name="current-header"/> 
                < /fo:inline> 
              < /heading> 
              < pagenum> 
                < fo:inline xsl:use-attribute-sets="__body__odd__header__pagenum"> 
                  < fo:page-number/> 
                < /fo:inline> 
              < /pagenum> 
            < /xsl:with-param> 
          < /xsl:call-template> 
        < /fo:block> 
      < /fo:static-content> 
    < /xsl:template> 

  2. Anything you want to put in the header must be contained within the fo:static-content tag and the fo:block:

    Step Information
    < xsl:template name="insertBodyOddHeader"> 
      < fo:static-content flow-name="odd-body-header"> 
        < fo:block xsl:use-attribute-sets="__body__odd__header"> 
          
        < /fo:block> 
      < /fo:static-content> 
    < /xsl:template> 

  3. To add a header image, use the fo:block-container and fo:block element to add and absolutely position the image. Use the code below:

    Step Information
    < fo:block-container xsl:use-attribute-sets="__header__image"> 
      < fo:block> 
        < fo:external-graphic src="url(Customization/OpenTopic/common/artwork/[image.name])"/> 
      < /fo:block> 
    < /fo:block-container> 
    [image.name] is the name of the logo file (located in cfg/common/artwork)
    Tip:If you want to set the size of the image, you can use the content-width attribute on fo:external-graphic.

  4. To add the document title to the header, use the fo:block element.

    1. Use the following code to insert the title text into the header:

      Step Information
      < fo:block xsl:use-attribute-sets="__headerTitleText"> 
        < xsl:value-of select="$title"/> 
      < /fo:block> 

    2. The contents of the block are defined by the variable $title. The title value is somewhat complicated to calculate for bookmaps, so calculating it once and setting it to a variable is most effective. You’ll need the following code at the top of your custom-xsl.xsl file (just below the < xsl:stylesheet> element):

      Step Information
      < xsl:variable name="title"> 
        < xsl:choose> 
          < xsl:when test="$map//*[contains(@class,' bookmap/mainbooktitle ')][1]"> 
            < xsl:apply-templates select="$map//*[contains(@class,' bookmap/mainbooktitle ')][1]"/> 
          < /xsl:when> 
          < xsl:when test="$map/*[contains(@class,' topic/title ')][1]"> 
            < xsl:apply-templates select="$map/*[contains(@class,' topic/title ')][1]"/> 
          < /xsl:when> 
          < xsl:when test="//*[contains(@class, ' map/map ')]/@title"> 
            < xsl:value-of select="//*[contains(@class, ' map/map ')]/@title"/> 
          < /xsl:when> 
          < xsl:otherwise> 
            < xsl:value-of select="/descendant::*[contains(@class, ' topic/topic ')][1]/*[contains(@class, ' topic/title ')]"/> 
          < /xsl:otherwise> 
        < /xsl:choose> 
      < /xsl:variable> 
      This variable definition uses the $map variable, and because this is defined in the default org.dita.pdf2 stylesheets, we don’t need to worry about it.

  5. To add multiple lines of text in your header, you can use multiple fo:block elements. This examples inserts two lines: one for the Company Name, and one for the Document Title and Page Number:

    Step Information
    < fo:block xsl:use-attribute-sets="__header_line_one">    < xsl:call-template name="insertVariable">      < xsl:with-param name="theVariableID" select="'Company Name'"/>    < /xsl:call-template>  < /fo:block>  < fo:block xsl:use-attribute-sets="__header_line_two">    < xsl:value-of select="$title"/>    < fo:leader leader-pattern="space"/>    < xsl:call-template name="insertVariable">      < xsl:with-param name="theVariableID" select="'Custom Page Number'"/>      < xsl:with-param name="theParameters">        < pagenum>          < fo:page-number/>        < /pagenum>      < /xsl:with-param>    < /xsl:call-template>  < /fo:block>  

    Tip:You can use variables (by calling the “insertVariable” template as above) to specify string values that will automatically be translated with the rest of your content. To add a variable value, follow the steps outlined in Setting Global Variables.
    Note:If you want to display the total page count (for example, “Page x of y”), you’ll need to use the Total Page Number guide.
    Note:If you do add several lines of text into the header, use the Adjusting the Header Size guide to adjust the header spacing so that the text won’t overlap.

  6. Combine all the code together into the header template and add it to the custom-xsl.xsl file located at cfg/fo/xsl/.

    Example
    The example below uses an image and a document title:
    < xsl:template name="insertBodyOddHeader"> 
      < fo:static-content flow-name="odd-body-header"> 
        < fo:block xsl:use-attribute-sets="__body__odd__header"> 
    
          < fo:block-container xsl:use-attribute-sets="__header__image"> 
            < fo:block> 
              < fo:external-graphic src="url(Customization/OpenTopic/common/artwork/[image.name])"/> 
            < /fo:block> 
          < /fo:block-container> 
    
          < fo:block xsl:use-attribute-sets="__headerTitleText"> 
            < xsl:value-of select="$title"/> 
          < /fo:block> 
    
        < /fo:block> 
      < /fo:static-content> 
    < /xsl:template> 
result
You added your custom header template to the custom-xsl.xsl file located in cfg/fo/xsl/.
Tip:If you want the same custom header to appear on your Table of Contents page, you need to add another template. You can just copy your custom header template and change the template name to “insertTocOddHeader” and the static-content flow-name to “odd-toc-header”.

postreq
Your custom header template contains new attribute-sets. See Adding Header Attributes to define these new attribute-sets and ensure your header displays correctly.
In step 5, if you did call the insertVariable template with a custom variable Id, you’ll need to set it up using the Setting Global Variables guide.
Adding Header Attributes

Define attribute-sets so that your header appears as expected.
prereq
Before you can add new attribute-sets, you must add a header template using the procedure in Editing a Header Template.  
context

While editing a header template, you added new attribute-sets. You need to define these attribute sets in the custom-attrs.xsl file (located in cfg/fo/attrs/) for your header to display correctly. Below we have sample attribute sets for the examples that we outlined in Editing a Header Template, however if you have used other ones, be sure to specify them as well. 

  1. The first attribute set that you need to add is “odd__header”. Below is a sample of some attributes that you may like, however feel free to add or remove any in order to change the styling of the header.

    Step Information
    < xsl:attribute-set name="odd__header"> 
      < xsl:attribute name="font-family"> sans-serif< /xsl:attribute> 
      < xsl:attribute name="font-size"> 10pt< /xsl:attribute> 
      < xsl:attribute name="font-weight"> normal< /xsl:attribute> 
      < xsl:attribute name="color"> black< /xsl:attribute> 
      < xsl:attribute name="margin-left"> 
        < xsl:value-of select="$page-margins"/> 
      < /xsl:attribute> 
      < xsl:attribute name="margin-right"> 
        < xsl:value-of select="$page-margins"/> 
      < /xsl:attribute> 
      < xsl:attribute name="padding-top"> 0px< /xsl:attribute> 
    < /xsl:attribute-set> 
    You may notice that in the custom-xsl.xsl file, we used the “__body__odd__header” attribute set, not the “odd__header” attribute set. However, because the “__body__odd__header” attribute set inherits all the attributes from “odd__header”, and “odd__header” is used more generally, it is more useful to edit this attribute set.
  2. If you’re using a header image, you need to create the “__header__image” attribute set. Below are some attribute settings that you can use to place the image in the top left hand corner of the header.

    Step Information
    < xsl:attribute-set name="__header__image"> 
      < xsl:attribute name="top"> 20pt< /xsl:attribute> 
      < xsl:attribute name="position"> absolute< /xsl:attribute> 
      < xsl:attribute name="left"> 
        < xsl:value-of select="$page-margins"/> 
      < /xsl:attribute> 
      < xsl:attribute name="text-align"> start< /xsl:attribute> 
    < /xsl:attribute-set> 
  3. Add the attribute sets for any of the other blocks or block-containers that you added in the Editing a Header Template guide. For example, if you added multiple lines of text in the header.

    Step Information
    Important:You must create an < xsl:attribute-set/> element for each attribute set referenced in your custom-xsl.xsl file or else the DITA-OT will display an error. So even if some of them are empty, make sure you have created them all.
    Here is a list of potentially useful attributes that you can use to format your header:

    • Text:
      • font-family
        • Supports serif, sans-serif, Helvetica, Times, Courier, Symbol, ZapfDingbats
      • font-size
      • font-weight
      • text-align
        • Supports left, right, center, justify
    • Borders:
      • border-before-style
        • Supports none, hidden, dotted, dashed, solid, double, groove, ridge, inset, outset
      • border-before-width
        • Specify a width for the top border in any units
      • border-before-color
      • Along with the same three options for border-after-, border-start-, border-end-
    • Spacing
      • padding-top, padding-bottom, padding-right, padding-left
      • margin-top, margin-bottom, margin-right, margin-left
result
You’re ready to publish with your new header. Here are some examples of various outputs:
Using the header image with attributes set in Step 2 and the document title with the text-align attribute set to “center”:
Using the multiple lines of text option explained in Step 5 in Editing a Header Template, changing the font-family to serif, adjusting the font-size and the spacing, and adding border-after attributes to the second line:
Adding a Background Color

Add a background color to your header or footer.
context

You want to add a background color to your header or footer.

Note: We’ll use the “insertBodyOddHeader” template as an example, but this can be used for any of the header or footer templates, just be sure to change the template name and the flow-name.
    Modifying the static-content.xsl file
  1. In order to add a background color, you”ll need to add two more fo groups into the header definitions located in the static-content.xsl file. Add the bolded lines below into your XSL file so that your main block is within a block-container.

    Expected Result
    < xsl:template name="insertBodyOddHeader"> 
      < fo:static-content flow-name="odd-body-header"> 
        < fo:block-container xsl:use-attribute-sets="__headerBackground"> 
          < fo:block xsl:use-attribute-sets="__body__odd__header"> 
            {{Content of Header}}
          < /fo:block> 
        < /fo:block-container> 
      < /fo:static-content> 
    < /xsl:template> 

  2. Modifying the custom-attrs.xsl file
  3. Now, you need to adjust the attribute sets that are located in your custom-attrs.xsl file. First, add a __headerBackground attribute set with the following contents:

    Expected Result
    < xsl:attribute-set name="__headerBackground"> 
      < xsl:attribute name="background-color"> #FF0000< /xsl:attribute> 
      < xsl:attribute name="position"> absolute< /xsl:attribute> 
      < xsl:attribute name="left"> 0< /xsl:attribute> 
      < xsl:attribute name="width"> 
        < xsl:value-of select="$page-width"/> 
      < /xsl:attribute> 
    < /xsl:attribute-set> 
    The bolded line above is the background-color attribute. Set the value of this node to the hexadecimal value of the color you want your header to be. In the example above, it is set to red.

  4. Next, you have to adjust the attribute set used on the fo:block element in Step 2. In this example, it is “__body__odd__header” but yours might be different. Add the following lines into the attribute set:

    Step Information
    < xsl:attribute name="padding-top"> 0.15in< /xsl:attribute> 
    < xsl:attribute name="padding-bottom"> 0.15in< /xsl:attribute> 
    < xsl:attribute name="margin-left"> 
      < xsl:value-of select="$page-margins"/> 
    < /xsl:attribute> 
    < xsl:attribute name="margin-right"> 
      < xsl:value-of select="$page-margins"/> 
    < /xsl:attribute> 
    Note:You can adjust the vertical location of your header content by adjusting the padding values.
  5. [Optional] You may also need to change the color of the header text if you’re using a dark background color. The code below will set the text color to white:

    Step Information
    < xsl:attribute name="color"> #fff< /xsl:attribute> 

result
You added a background color to your header or footer. An example of the output:

Adjusting the Header Size

Adjust the size and alignment of your header.
Let’s look at a sample header to understand which attributes to modify to position your header exactly where you want it. At the bottom of the page, a screenshot of the custom-attrs.xsl file displays each attribute used to adjust the header dimensions.
A
The distance between the top of the page and the top of the body text
You’ll need to modify the “page-margin-top” variable. This is defined outside any attribute-set in the root of the stylesheet. The default is 20mm.
B
The distance between the top of the page and the top of the header image
You’ll need to modify the “top” attribute of the “__header__image” attribute set. This will not affect any of the other positioning within the header because the image is positioned absolutely.
C
The distance between the top of the page and the top of the header text
You’ll need to modify the “padding-top” attribute of the “odd__header” attribute set. Modifying this value will also change the size of the header
D
The distance between the bottom of the header text and the bottom of the header background
You’ll need to modify the “padding-bottom” attribute of the “odd__header” attribute set. Modifying this value won’t change the position of the body text (use A).