Edit online

When you create a new transformation scenario or edit an existing one, a configuration dialog box allows you to customize the transformation with various options in several tabs.

The Templates tab is available for DITA OT transformations with WebHelp Responsive, WebHelp Responsive with Feedback, or PDF - based on HTML5 & CSS output types and it provides a set of built-in publishing templates. You can use one of them to publish your documentation or as a starting point for a new publishing template.

Figure 1: Templates Tab

Filtering and Previewing Templates

You can click on the tags at the top of the pane to filter the templates and narrow your search. Each built-in template also includes an Online preview icon in the bottom-right corner that opens a webpage in your default browser providing a sample of how the main page will look when that particular template is used to generate the output.

Built-in Templates Locations

Oxygen XML Author scans the following locations to find the built-in templates to display in the dialog box:
  • WebHelp Responsive Templates - All built-in WebHelp Responsive publishing templates are stored in the following directory: DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/templates.
  • PDF - based on HTML5 & CSS - All built-in PDF publishing templates are stored in the following directories:
    • DITA-OT-DIR/plugins/com.oxygenxml.pdf.css/templates
    • DITA-OT-DIR/plugins/com.oxygenxml.webhelp.responsive/templates

Custom Templates Locations

Oxygen XML Author scans the locations specified in the DITA > Publishing preferences page to find custom templates to display in the dialog box. You can access that preferences page directly from the Template tab by clicking on the Configure Publishing Templates Gallery link.

Selecting Custom Templates

Once you are finished configuring your template, you can click the Choose Custom Publishing Template link to select your template.

You can also add your custom templates to the list of templates displayed in the Templates tab. To do this, store them in a directory, then click the Configure Publishing Templates Gallery link to open the DITA > Publishing preferences page where you can add that directory to the list. All the templates contained in your template directory will be displayed in the preview pane along with all the built-in templates.

Save Template As Button

You can use the Save template as button (at the bottom-left of the transformation dialog box) to export the currently selected template into a new template package that can be used as a starting point to create your own custom template. Clicking this button will open a template package configuration dialog box that contains some options and displays the parameters that will be exported to your template package.

Template Errors

When the Templates tab is opened, all templates (built-in and custom) are loaded and validated. Specifically, certain elements in the template descriptor file are checked for validity. If errors are encountered that prevents the template from loading, the following message will be displayed toward the bottom of the dialog box:

If you click the More details link, a window will open with more information about the encountered error. For example, it might offer a hint for which element is missing from the expected descriptor file structure.

Also, if a template could be loaded, but certain elements could not be found in the descriptor file, a warning icon () will be displayed on the template's image (in the Templates tab of the transformation dialog box). For example, this happens if a valid preview-image element cannot be found.

Sharing Publishing Template

To share a publishing template with others, following these steps:

  1. Copy your template in a new folder.
  2. Go to Options > Preferences > DITA > Publishing and add that new folder to the list.
  3. Switch the option as the bottom of that preferences page to Project Options.
  4. Share your project file (.xpr).

For more information about customizing publishing templates, watch our video demonstration: