Customizing Headers and Footers

Here should go questions about transforming XML with XSLT and FOP.
gwhite
Posts: 70

Customizing Headers and Footers

Wed Sep 19, 2012 7:09 pm

I've combed through this forum for details on how to modify the footer or header of a PDF and seen the suggestion repeated that one go to one of the other DITA or XML forums for specifics. I've been to the main site recommended, but the information there is usually about the DITA-OT and not oXygen. And often they end by referring you to the DITA-OT documentation! Could you help me please with an oXygen implementation of this solution?

Here is what I have done: 1) I've found the static-content.xsl file in ../DITA-OT/demo/fo/xsl/fo and seen the header and footer insert templates in that xsl. 2) I've found the static-content-attr.xsl file where the attributes of template parameters are kept. But I do not see where variables like those in the following two code examples are set.

Code: Select all

   <xsl:template name="insertBodyStaticContents">
        <xsl:call-template name="insertBodyFootnoteSeparator"/>
        <xsl:call-template name="insertBodyOddFooter"/>
        <xsl:call-template name="insertBodyEvenFooter"/>
        <xsl:call-template name="insertBodyOddHeader"/>
        <xsl:call-template name="insertBodyEvenHeader"/>
        <xsl:call-template name="insertBodyFirstHeader"/>
        <xsl:call-template name="insertBodyFirstFooter"/>
        <xsl:call-template name="insertBodyLastHeader"/>
        <xsl:call-template name="insertBodyLastFooter"/>
    </xsl:template>
...

    <xsl:template name="insertBodyOddFooter">

        <fo:static-content flow-name="odd-body-footer">
            <fo:block xsl:use-attribute-sets="__body__odd__footer">
                <xsl:call-template name="insertVariable">
                    <xsl:with-param name="theVariableID" select="'Body odd footer'"/>
                    <xsl:with-param name="theParameters">
                        <heading>
                            <fo:inline xsl:use-attribute-sets="__body__odd__footer__heading">
                                <fo:retrieve-marker retrieve-class-name="current-header"/>
                            </fo:inline>
                        </heading>
                        <pagenum>
                            <fo:inline xsl:use-attribute-sets="__body__odd__footer__pagenum">
                                <fo:page-number/>
                            </fo:inline>
                        </pagenum>
                    </xsl:with-param>
                </xsl:call-template>
            </fo:block>
        </fo:static-content>

    </xsl:template>



My first question is: where are these variables in the xsl files set? At what point can I ask the xsl to pick up, say, my company name and insert it into the appropriate variable? Second, is it not possible to use Configure Transformation Scenarios in oXygen to set parameters to accomplish this? If so, how?

The DITA-OT Reference lists args.ftr and args.hdr as parameters that can be set for a footer/header. The definition says, "Specifies the location of a well-formed XML file containing your custom running footer [header] for the document body. Corresponds to xslt parameter FTR [HDR]. Note: The fragment must be valid XML with a single root element. Common practice is to place all content into <div>.

Can you give me an example of what xml would implement this? And again, how are those variables in the xsl and attributes files set?

If the solution is not fairly straightforward, this seems to be a big opportunity for a feature that would greatly simplify use of the product. I can't imagine I'm the only person with this need.

Thanks!

Gary
sorin_ristache
Posts: 4144

Re: Customizing Headers and Footers

Thu Sep 20, 2012 12:06 pm

Hi Gary,

gwhite wrote:I've been to the main site recommended, but the information there is usually about the DITA-OT and not oXygen. And often they end by referring you to the DITA-OT documentation! Could you help me please with an oXygen implementation of this solution?


Oxygen installs the DITA Open Toolkit in directory [Oxygen-install-dir]/frameworks/dita/DITA-OT, so any modification of the DITA-OT stylesheets should be applied to the files from this directory.

gwhite wrote:But I do not see where variables like those in the following two code examples are set.

Code: Select all

   <xsl:template name="insertBodyStaticContents">
        <xsl:call-template name="insertBodyFootnoteSeparator"/>
        <xsl:call-template name="insertBodyOddFooter"/>
        <xsl:call-template name="insertBodyEvenFooter"/>
        <xsl:call-template name="insertBodyOddHeader"/>
        <xsl:call-template name="insertBodyEvenHeader"/>
        <xsl:call-template name="insertBodyFirstHeader"/>
        <xsl:call-template name="insertBodyFirstFooter"/>
        <xsl:call-template name="insertBodyLastHeader"/>
        <xsl:call-template name="insertBodyLastFooter"/>
    </xsl:template>
...

    <xsl:template name="insertBodyOddFooter">

        <fo:static-content flow-name="odd-body-footer">
            <fo:block xsl:use-attribute-sets="__body__odd__footer">
                <xsl:call-template name="insertVariable">
                    <xsl:with-param name="theVariableID" select="'Body odd footer'"/>
                    <xsl:with-param name="theParameters">
                        <heading>
                            <fo:inline xsl:use-attribute-sets="__body__odd__footer__heading">
                                <fo:retrieve-marker retrieve-class-name="current-header"/>
                            </fo:inline>
                        </heading>
                        <pagenum>
                            <fo:inline xsl:use-attribute-sets="__body__odd__footer__pagenum">
                                <fo:page-number/>
                            </fo:inline>
                        </pagenum>
                    </xsl:with-param>
                </xsl:call-template>
            </fo:block>
        </fo:static-content>

    </xsl:template>


My first question is: where are these variables in the xsl files set? At what point can I ask the xsl to pick up, say, my company name and insert it into the appropriate variable? Second, is it not possible to use Configure Transformation Scenarios in oXygen to set parameters to accomplish this? If so, how?


The PDF output is created by a DITA-OT plugin installed in directory [DITA-OT]/demo/fo. This plugin has some special rules for customization, so it cannot be customized with the Configure Transformation Scenarios dialog box. The parameters and custom XSLT templates must be set in one of the XSLT stylesheets from one of the sub-directories of [DITA-OT]/demo/fo.

For example if you want to insert your company name in the footer of every odd page in the body of the PDF result (that is excluding the pages with the front cover, Table of Contents, Table of Figures, Index, etc.) then you must add a custom XSLT template like the above one (a template with the attribute name="insertBodyOddFooter" that creates an element <fo:static-content flow-name="odd-body-footer">) in a custom XSLT stylesheet added in the directory [DITA-OT]/demo/fo/Customization as you can read in the README.txt file from this directory.

gwhite wrote:The DITA-OT Reference lists args.ftr and args.hdr as parameters that can be set for a footer/header. The definition says, "Specifies the location of a well-formed XML file containing your custom running footer [header] for the document body. Corresponds to xslt parameter FTR [HDR]. Note: The fragment must be valid XML with a single root element. Common practice is to place all content into <div>.

Can you give me an example of what xml would implement this? And again, how are those variables in the xsl and attributes files set?


If you look in the Parameters tab of the dialog box for configuring a DITA transformation the parameters args.hdr and args.ftr are available only in the XHTML based transformation (DITA Map XHTML, DITA Map WebHelp, etc), not in the PDF one. As I said above the reason is the special way of customizing the DITA-OT plugin for PDF output.

In the XHTML-based transformation you should set the value of the parameter args.hdr or args.ftr in the Parameters tab to the file path of a well-formed XHTML file that contains the header or footer fragment that will be inserted in each output XHTML page.

gwhite wrote:If the solution is not fairly straightforward, this seems to be a big opportunity for a feature that would greatly simplify use of the product. I can't imagine I'm the only person with this need.


We will try to find a more straightforward way of customizing the DITA PDF output but currently the architecture of the DITA-OT PDF plugin does not seem to lend itself to that.


Regards,
Sorin
gwhite
Posts: 70

Re: Customizing Headers and Footers

Fri Sep 21, 2012 5:39 pm

The missing piece of information, which I found after digging further on my own, and which is not mentioned as far as I can tell in the documentation or in any of these forum discussions, is very simple, and here it is for posterity. :wink:

You set up text-based information, like company name, for inclusion in the header or footer in the en_US.xml (or other languages's xml files) in the Customization/common/vars folder. You have to do it for all languages of documentation you produce. Modify lines like these in that file:

Code: Select all

    <!-- The footer that appears on the odd-numbered table of contents
         pages. -->
    <variable id="Toc odd footer">ABC Company, Inc.</variable>

    <!-- The footer that appears on the even-numbered table of contents
         pages. -->
    <variable id="Toc even footer">ABC Company, Inc.</variable>


Do it for preface, TOC, body, everywhere where you want to footer/header to appear. Of course, you can put copyright info here or any other constant information.

Then you have to set the attributes of the header/footer (centering and so forth) by including the attribute settings for headers/footers in the Customization/fo/attrs/custom.xml file:

Code: Select all

<xsl:attribute-set name="odd__footer"> <xsl:attribute name="text-align">center</xsl:attribute>
  <xsl:attribute name="end-indent">10pt</xsl:attribute>
  <xsl:attribute name="space-after">10pt</xsl:attribute>
  <xsl:attribute name="space-after.conditionality">retain</xsl:attribute> </xsl:attribute-set>
<xsl:attribute-set name="even__footer">
  <xsl:attribute name="text-align">center</xsl:attribute>
  <xsl:attribute name="start-indent">10pt</xsl:attribute>
  <xsl:attribute name="space-after">10pt</xsl:attribute>
  <xsl:attribute name="space-after.conditionality">retain</xsl:attribute>
</xsl:attribute-set>


That's all there is to it! There's no requirement to create special variables or anything. It is very straightforward.

Gary
sorin_ristache
Posts: 4144

Re: Customizing Headers and Footers

Fri Sep 21, 2012 5:49 pm

Hi Gary,

You are right, of course, and it was missing from my post!


Thank you for posting these details,
Sorin
fmasson85
Posts: 4
Location: Québec City, Canada

Re: Customizing Headers and Footers

Fri Nov 16, 2012 7:20 pm

HI,

I was wondering how I could create three zones in my footer : for exemple, Page number on the right, Name of the company is centered and the name of the chapter is on the left.

Thanks fo any indications on how to achieve this.
sorin_ristache
Posts: 4144

Re: Customizing Headers and Footers

Mon Nov 19, 2012 1:56 pm

Hi,

fmasson85 wrote:I was wondering how I could create three zones in my footer : for exemple, Page number on the right, Name of the company is centered and the name of the chapter is on the left.


By default the DITA Map PDF built-in transformation adds the page number and chapter name in the page header. If you want to add them in the footer you have to customize the XSLT stylesheets from directory [Oxygen-install-dir]/frameworks/dita/DITA-OT/plugins/org.dita.pdf2/Customization (in Oxygen versions older than 14.1 the directory was [Oxygen-install-dir]/frameworks/dita/DITA-OT/demo/fo/Customization) and add two custom templates for adding for your desired footer content in both even page footers and odd page footers, as described above:

sorin wrote:For example if you want to insert your company name in the footer of every odd page in the body of the PDF result (that is excluding the pages with the front cover, Table of Contents, Table of Figures, Index, etc.) then you must add a custom XSLT template like the above one (a template with the attribute name="insertBodyOddFooter" that creates an element <fo:static-content flow-name="odd-body-footer">) in a custom XSLT stylesheet added in the directory [DITA-OT]/demo/fo/Customization as you can read in the README.txt file from this directory.



gwhite wrote:I've combed through this forum for details on how to modify the footer or header of a PDF and seen the suggestion repeated that one go to one of the other DITA or XML forums for specifics. I've been to the main site recommended, but the information there is usually about the DITA-OT and not oXygen. And often they end by referring you to the DITA-OT documentation! Could you help me please with an oXygen implementation of this solution?

Here is what I have done: 1) I've found the static-content.xsl file in ../DITA-OT/demo/fo/xsl/fo and seen the header and footer insert templates in that xsl. 2) I've found the static-content-attr.xsl file where the attributes of template parameters are kept. But I do not see where variables like those in the following two code examples are set.

Code: Select all

   <xsl:template name="insertBodyStaticContents">
        <xsl:call-template name="insertBodyFootnoteSeparator"/>
        <xsl:call-template name="insertBodyOddFooter"/>
        <xsl:call-template name="insertBodyEvenFooter"/>
        <xsl:call-template name="insertBodyOddHeader"/>
        <xsl:call-template name="insertBodyEvenHeader"/>
        <xsl:call-template name="insertBodyFirstHeader"/>
        <xsl:call-template name="insertBodyFirstFooter"/>
        <xsl:call-template name="insertBodyLastHeader"/>
        <xsl:call-template name="insertBodyLastFooter"/>
    </xsl:template>
...

    <xsl:template name="insertBodyOddFooter">

        <fo:static-content flow-name="odd-body-footer">
            <fo:block xsl:use-attribute-sets="__body__odd__footer">
                <xsl:call-template name="insertVariable">
                    <xsl:with-param name="theVariableID" select="'Body odd footer'"/>
                    <xsl:with-param name="theParameters">
                        <heading>
                            <fo:inline xsl:use-attribute-sets="__body__odd__footer__heading">
                                <fo:retrieve-marker retrieve-class-name="current-header"/>
                            </fo:inline>
                        </heading>
                        <pagenum>
                            <fo:inline xsl:use-attribute-sets="__body__odd__footer__pagenum">
                                <fo:page-number/>
                            </fo:inline>
                        </pagenum>
                    </xsl:with-param>
                </xsl:call-template>
            </fo:block>
        </fo:static-content>

    </xsl:template>




Regards,
Sorin
pcroce
Posts: 2

Re: Customizing Headers and Footers

Thu Jun 23, 2016 6:21 pm

I've followed this procedure for a week and found the following - if it will help anyone else!

The step to: Add the following templates to this file (copied from org.dita.pdf2\xsl\fo\static-content.xsl) and customize them in any way you want:

<xsl:template name="insertBodyOddHeader">
<xsl:template name="insertBodyEvenHeader">
<xsl:template name="insertBodyOddFooter">
<xsl:template name="insertBodyEvenFooter">

Is not really required and unless you know what you are customizing, it will not work "as is". In other words, don't make this edit.

You do however, have to edit the <lang>.xml file (e.g. eng.xml) that is in the <oXygen_install_dir>\frameworks\dita\DITA-OT\plugins\org.dita.pdf2\cfg\common\vars folder. That file is pretty self-explanatory - just know that you add the footer information as such, for example (with ABC-XYZ being that which will be shown in the footer):

<!-- The footer that appears on odd-numbered pages. -->
<variable id="Body odd footer">ABC-XYZ</variable>

Return to “XSLT and FOP”

Who is online

Users browsing this forum: No registered users and 0 guests