Edit online

Publishing Template Package Contents for PDF Customizations

An Oxygen Publishing Template for PDF output must contain a template descriptor file and at least one CSS file, and may contain other resources (such as graphics, XSLT files, etc.). All the template resources can be stored in either a ZIP archive or in a folder. It is recommended to use a ZIP archive because it is easier to share with others.

Edit online

Template Descriptor File

Each publishing template includes a descriptor file that defines the meta-data associated with template. It is an XML file with certain elements that defines all the resources included in a template (such as CSS files, images, and transformation parameters).

The template descriptor file must have the .opt file extension and must be located in the templates' root folder.

A PDF template descriptor might look like this:

<publishing-template>
    <name>Flowers</name>

    <pdf>
        <tags>
            <tag>purple</tag>
            <tag>light</tag>
        </tags>
        <preview-image file="flowers-preview.png"/>
        
        <resources>
            <css file="flowers.css"/>
        </resources>
        
        <parameters>
            <parameter name="figure.title.placement" value="top"/>
        </parameters>
    </pdf>
</publishing-template>
Tip: It is recommended to edit the template descriptor in Oxygen XML Editor/Author because it provides content completion and validation support.

Template Name and Description

Each template descriptor file requires a <name> element. This information is displayed as the name of the template in the transformation scenario dialog box.

Optionally, you can include a <description> and it displayed when the user hovers over the template in the transformation scenario dialog box.

<publishing-template>
    <name>Flowers</name>
    <description>Flowers themed light colored template</description>
    ...

Template Author

Optionally, you can include author information in the descriptor file and it displayed when the user hovers over the template in the transformation scenario dialog box. This information might be useful if users run into an issue or have questions about a certain template.

If you include the <author> element, a <name> is required and optionally you can include <email>, <organization>, and <organizationUrl>.

<publishing-template>
    ...
    <author>
      <name>John Doe</name>
      <email>jdoe@example.com</email>
      <organization>ACME</organization>
      <organizationUrl>http://www.example.com/jdoe</organizationUrl>
    </author>
    ...

PDF Element

The <pdf> element contains various details about the template and its resources that define the PDF output. It is a required element if you intend on using a DITA Map to PDF transformation scenario. The elements that are allowed in this <pdf> section specify the template tags, template preview image, resources (such as CSS files), transformation parameters, or XSLT extensions.

    <pdf>
        <tags>
          ...
        </tags>
        <preview-image file="MyPreview.png"/>

        <resources>
          ...
        </resources>

        <parameters>
          ...
        </parameters>
    </pdf>

Template Tags

The <tags> section provides meta information about the template (such as color theme). Each tag is displayed at the top of the Templates tab window in the transformation scenario dialog box and they help the user filter and find particular templates.

<publishing-template>
    ...
    <pdf>
      <tags>
        <tag>purple</tag>
        <tag>light</tag>
      </tags>

Template Preview Image

The <preview-image> element is used to specify an image that will be displayed in the transformation scenario dialog box. It provides a visual representation of the template to help the user select the right template. The image dimensions should be 200 x 115 pixels and the supported image formats are: JPEG, PNG, or GIF.

You can also include an <online-preview-url> element to specify the URL of a published sample of your template. This will display an Online preview icon in the bottom-right corner of the image in the transformation scenario dialog box and if the user clicks that icon, it will open the specified URL in their default browser.
<publishing-template>
    ...
    <pdf>
      ...
      <preview-image file="ashes/ashes-tree.png"/>
      <online-preview-url=https://www.example.com/samples/tiles/ashes</online-preview-url>
Edit online

Template Resources

The <resources> section of the descriptor file specifies a set of resources (CSS files) that are used to customize various components in the generated output. These resources will be copied to the output folder during the transformation process. At least one CSS file must be included (using the <css> element).
<publishing-template>
    ...
    <pdf>
      ...                
      <resources>            
          <css file="css/custom_styles.css"/>
          <css file="css/custom_fonts.css"/>
      </resources>
Note: All relative paths specified in the descriptor file are relative to the template root folder.
Edit online

Transformation Parameters

You can also set one or more transformation parameters in the descriptor file.
<publishing-template>
    ...    
    <pdf>
      ...
      <parameters>
        <parameter name="show.changes.and.comments" value="yes"/>      
      </parameters>
    </pdf>

The following information can be specified in the <parameters> element:

Parameter name
The name of the parameter. It may be one of the transformation parameters listed in the Parameters tab of the DITA Map PDF - based on HTML5 & CSS transformation scenario or a DITA-OT PDF-based output parameter.
Note: It is not recommended to specify an input/output parameter in the descriptor file (such as the input Map, DITAVAL file, or temporary directory).
Attention: JVM arguments like -Xmx cannot be specified as a transformation parameter.
Parameter Value
The value of the parameter. It should be a relative path to the template root folder for file paths parameters.
Parameter Type
The type of the parameter: string or filepath. The string value is default.

After creating a publishing template and adding it to the templates gallery, when you select the template in the transformation scenario dialog box, the Parameters tab will automatically be updated to include the parameters defined in the descriptor file. These parameters are displayed in italics.

Edit online

XSLT Extension Points

The publishing templates support one or more XSLT extension points. They can be specified using the <xslt> element in the descriptor file using the following structure:
<publishing-template>
    ...
    <pdf>
        ...        
        <xslt>
            <extension 
              id="com.oxygenxml.pdf.css.xsl.merged2html5"
              file="xslt/merged2html5Extension.xsl"/>
            <extension
              id="com.oxygenxml.pdf.css.xsl.merged2merged"
              file="xslt/merged2mergedExtension.xsl"/>
        </xslt>

For more information about the available extension points, see: XSLT Extensions for PDF Transformations.

Edit online

Combining PDF and WebHelp Responsive Customizations in a Template Package

An Oxygen Publishing Template package can contain both a PDF and WebHelp Responsive customization in the same template package and you can use that same template in both types of transformations. The template descriptor file can define the customization for both types by including both a <webhelp> and <pdf> element and some of the resources can be reused. Resources referenced in elements in the <webhelp> element will only be used for WebHelp transformations, and resources referenced in the elements in the <pdf> element will only be used in PDF transformations.
<publishing-template>
    <name>Flowers</name>
    <description>Flowers themed light-colored template</description>

    <webhelp>
        <tags>
            <tag>purple</tag>
            <tag>light</tag>
        </tags>
        <preview-image file="flowers-preview.png"/>
        <resources>
            <css file="flowers-wh.css"/>
            <css file="flowers-page-styling.css"/>
        </resources>
        <parameters>
            <parameter name="webhelp.show.main.page.tiles" value="no"/>
            <parameter name="webhelp.show.main.page.toc" value="yes"/>
        </parameters>
    </webhelp>
    <pdf>
        <tags>
            <tag>purple</tag>
            <tag>light</tag>
        </tags>
        <preview-image file="flowers-preview.png"/>
        <resources>
            <css file="flowers-pdf.css"/>
            <css file="flowers-page-styling.css"/>
        </resources>
        <parameters>
            <parameter name="show.changes.and.comments" value="yes"/>"/>
        </parameters>
    <pdf>
</publishing-template>