History | Edit

DITA Open Toolkit PDF output can be customized in several ways:
  • Creating a DITA Open Toolkit plugin that adds extensions to the PDF plugin. More details can be found in the DITA Open Toolkit Documentation.
  • Creating a customization directory and using it from the PDF transformation scenario. A small example of this procedure can be found below.

How to Create a Customization Directory for PDF Output

The following procedure explains how to do a basic customization of the PDF output by setting up a customization directory. An example of a common use case is embedding a company logo image in the front matter of the book.

  1. Copy the entire directory: DITA-OT-DIR\plugins\org.dita.pdf2\Customization to another location (for instance, C:\Customization).
  2. Copy your logo image to: C:\Customization\common\artwork\logo.png.
  3. Rename C:\Customization\catalog.xml.orig to: C:\Customization\catalog.xml.
  4. Open the catalog.xml in Oxygen XML Editor and uncomment this line:
      <!--uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/-->   

    It now looks like this:

    <uri name="cfg:fo/xsl/custom.xsl" uri="fo/xsl/custom.xsl"/>
  5. Rename the file: C:\Customization\fo\xsl\custom.xsl.orig to: C:\Customization\fo\xsl\custom.xsl
  6. Open the custom.xsl file in Oxygen XML Editor and create the template called createFrontCoverContents for DITA-OT 2.5.2 (or createFrontMatter_1.0 for DITA-OT 1.8.5).
    Tip: You can copy the same template from DITA-OT-DIR\plugins\org.dita.pdf2\xsl\fo\front-matter.xsl and modify it in whatever way necessary to achieve your specific goal. This new template in the custom.xsl file will override the same template from DITA-OT-DIR\plugins\org.dita.pdf2\xsl\fo\front-matter.xsl.

    DITA OT 2.5.2 Example:

    For example, if you are using DITA OT 2.5.2, the custom.xsl could look like this:
    <?xml version='1.0'?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:fo="http://www.w3.org/1999/XSL/Format"
        version="2.0">
      
    <xsl:template name="createFrontCoverContents">
     <!-- set the title -->
     <fo:block xsl:use-attribute-sets="__frontmatter__title">
      <xsl:choose>
       <xsl:when test="$map/*[contains(@class,' topic/title ')][1]">
        <xsl:apply-templates select="$map/*[contains(@class,' topic/title ')][1]"/>
          </xsl:when>
          <xsl:when test="$map//*[contains(@class,' bookmap/mainbooktitle ')][1]">
            <xsl:apply-templates select="$map//*[contains
                                           (@class,' bookmap/mainbooktitle ')][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>
     </fo:block>
        
     <!-- set the subtitle -->
     <xsl:apply-templates select="$map//*[contains
                                              (@class,' bookmap/booktitlealt ')]"/>
     <fo:block xsl:use-attribute-sets="__frontmatter__owner">
      <xsl:apply-templates select="$map//*[contains(@class,' bookmap/bookmeta ')]"/>
     </fo:block>
      
     <!-- Load the image logo -->
      <fo:block text-align="center" width="100%">
       <fo:external-graphic
          src="url({concat($artworkPrefix, 
                              '/Customization/OpenTopic/common/artwork/logo.png')})"
        />
      </fo:block>
     </xsl:template>
    
    </xsl:stylesheet>

    DITA OT 1.8.5 Example:

    For example, if you are using DITA OT 1.8.5, the custom.xsl could look like this:
    <?xml version='1.0'?>
    <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
        xmlns:fo="http://www.w3.org/1999/XSL/Format"
        version="1.1">
    
    <xsl:template name="createFrontMatter_1.0">
       <fo:page-sequence master-reference="front-matter" 
                             xsl:use-attribute-sets="__force__page__count">
         <xsl:call-template name="insertFrontMatterStaticContents"/>
           <fo:flow flow-name="xsl-region-body">
             <fo:block xsl:use-attribute-sets="__frontmatter">
         <!-- set the title -->
               <fo:block xsl:use-attribute-sets="__frontmatter__title">
                <xsl:choose>
                 <xsl:when test="$map/*[contains(@class,' topic/title ')][1]">
         <xsl:apply-templates select="$map/*[contains(@class,' topic/title ')][1]"/>
                      </xsl:when>
        <xsl:when test="$map//*[contains(@class,' bookmap/mainbooktitle ')][1]">
         <xsl:apply-templates select="$map//*[contains
                                        (@class,' bookmap/mainbooktitle ')][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>
         </fo:block>
    
      <!-- set the subtitle -->
         <xsl:apply-templates select="$map//*[contains
                                               (@class,' bookmap/booktitlealt ')]"/>
    
            <fo:block xsl:use-attribute-sets="__frontmatter__owner">
                <xsl:apply-templates select="$map//*[contains
                                                   (@class,' bookmap/bookmeta ')]"/>
            </fo:block>
                       
            <fo:block text-align="center" width="100%">
               <fo:external-graphic src="url({concat($artworkPrefix,
                            '/Customization/OpenTopic/common/artwork/logo.png')})"/>
             </fo:block>
    
        </fo:block>
    
       <!--<xsl:call-template name="createPreface"/>-->
    
                </fo:flow>
            </fo:page-sequence>
            <xsl:call-template name="createNotices"/>
        </xsl:template>
    </xsl:stylesheet>
  7. Edit the DITA Map PDF transformation scenario and in the Parameters tab, set the customization.dir parameter to C:\Customization.
Tip: For other specific examples, see DITA-OT 2.x Documentation - PDF Customization Plugin.