How to Modify the Cover Page in the DITA Open Toolkit PDF Plugin

This tutorial uses the DITA Open Toolkit 1.4.2.1 and the corresponding PDF plugin release, and Wrycan's demo text. This assumes you have a working DITA environment and can run the default formatting with PDF plugin. If you don't know how to do this, contact us and we can post an example of how to do this! We will be working in the demo/fo/Customization directory of the open toolkit as shown in the image below.

1. With our sample content, the cover page of the document contains plain title text slightly above the center of an empty page:

Wrycan® Lorem Ipsum Test

We are going to modify this so that our company logo appears below the title text.

2. In order to modify the cover page, we first need to figure out which stylesheet creates the cover sheet.  The method I find most useful is to run a full-text search the demo/fo directory.  Searching for terms like "cover" and "cover sheet" yield no results in this case, so the next thing to do is look at the xsl files themselves.  Starting with demo/fo/xsl/fo/root-processing.xsl we can see there is a template called createFrontMatter. Searching in the XSLs for this template reveals that it is in demo/fo/xsl/front-matter.xsl.

3. The next step is to modify the template.  In order to do this, copy demo/fo/Customization/fo/xsl/custom.xsl.orig to custom.xsl and copy the createFrontMatter template into the copied XSL.  The logo image is going to be added below the subtitle, so below the template call with the "set the subtitle" code comment.  Add the code below underneath the subtitle template:
<fo:block text-align="center" width="100%">
<fo:external-graphic src="url({concat($artworkPrefix, '/Customization/OpenTopic/common/artwork/logo.png')})"/>
fo:block>

The parameter $artworkPrefix is passed in during the build process and the string "/Customization/OpenTopic/common/artwork/" is created for where our logo image is going to end up during processing.

4. Now that the code has been added, we need to actually add the logo.  To do this just copy an image file of the name logo.png into demo/fo/Customization/common/artwork folder or use ours as shown at the end of this post.

5. The last step is to tell the plugin that we have made customizations.  In order to do this, copy demo/fo/Customization/catalog.xml.orig to catalog.xml and then open the copied file and edit the 10th row to uncomment the code from:

<!--uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/-->

to: <uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/> and save the file.

6. This should create the output below on the cover sheet of the pdf.  There are many different ways the cover sheet can be customized and this is just one small example.  If you have some ideas for other examples you would like to see, contact us!

Wrycan® Lorem Ipsum Test