Publishing Template Package Contents for PDF Customizations
Edit online

An Oxygen Publishing Template package must contain a template descriptor file and some other resources (such as CSS files). All the template resources can be stored in either a ZIP archive or in a folder. It is recommended to use a ZIP archive when you need it to share with others.

Template Descriptor File
Edit online

Each publishing template includes a descriptor file that defines the meta-data associated with template. It is an XML file that defines all the resources included in a template (such as CSS files 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 information.

<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 output. 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>

Template Resources
Edit online

The resources section of the descriptor file specifies a set of resources (CSS files) that are used to customize various components in generated output. These resources will be copied to the output folder during the transformation process. At least one CSS file must be included, while the other types of resources are optional.
<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.

XSLT Extension Points
Edit online

The publishing template allows supports one or more XSLT extension points. They can be specified 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.

Transformation Parameters
Edit online

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 parameter 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 to 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.

Combining PDF and WebHelp Responsive Customizations in a Template Package
Edit online

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.
<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>