Edit online

Customizing New Document Templates

You can customize certain aspects of your custom document templates. For example, you can customize the icons or add placeholders or hints to assist authors.

Customizing the Icons for a Document Template

If you want to customize the icons to be used for document templates, use a properties file to specify the icons using the following procedure:
  1. In Oxygen XML Editor/Author, create a new properties file or edit an existing one following these guidelines:
    1. If you want to create a new properties file, you can use the Properties template found in the New Document folder in the New document wizard. If you want to edit an existing template, you can find them within the subfolders in the templates folder for each framework (for example, the DITA topic properties file is located in: OXYGEN_INSTALL_DIR/frameworks/dita/templates/topic/topic.properties).
    2. Use the same name as your custom template file except with a .properties extension (for example, MyTemplate.properties).
    3. In this properties file, specify the paths to the icons that will be used in the new file wizard. The properties file should look like this:
      type=general
      smallIcon=../icons/Article_16.png
      bigIcon=../icons/Article_48.png
      Tip: For DITA files, the type property needs to be set to dita. Otherwise, the template will not appear in the dialog box for creating new DITA topics from the DITA Maps Manager. For all other types of files, set it to general. The icons specified in this properties file will only be used for the new file wizards and not in any other part of the interface.
  2. Save the properties file in the same directory as your custom template (this directory should be inside your custom framework folder).
  3. Create an archive that only contains your custom framework folder (one single folder) and upload the changes to your framework to Web Author.

Result: The icon should now be visible for the custom document template when creating new documents.

Configuring the Displayed Names for Document Templates

To change the name that is displayed for a document template, use the following procedure:
  1. In Oxygen XML Editor/Author, create a new properties file or edit an existing one. If you want to create a new properties file, you can use the Properties template found in the New Document folder in the New document wizard. If you want to edit an existing template, you can find them within the subfolders in the templates folder for each framework (for example, the DITA topic properties file is located in: OXYGEN_INSTALL_DIR/frameworks/dita/templates/topic/topic.properties).
  2. Use the same name as your custom template file except with a .properties extension (for example, MyTemplate.properties).
  3. Add a displayName property in the properties file:
    displayName=My Template Name
  4. [Optional] You can add a prefix or suffix to the file name that is proposed in the New document wizard by using the filenamePrefix or filenameSuffix properties like this:
    filenamePrefix=prod_
    filenameSuffix=_test
  5. Save the properties file in the same directory as your custom template (this directory should be inside your custom framework folder).
  6. Create an archive that only contains your custom framework folder (one single folder) and upload the changes to your framework to Web Author.

Result: The new name for the custom document template should now be visible when creating new documents.

Adding Placeholders or Hints in a Document Template

A document template may contain empty elements and it may not be clear to the Author what should be inserted. You can define placeholders in document templates that provide hints for Authors to help them understand what type of content should be added in any particular empty element within the document. The placeholder text is specified using a processing instruction and the placeholders are removed when the Author inserts content in the corresponding element.

To define placeholders in a custom document template to provide authors with hints, follow this procedure:
  1. In Oxygen XML Editor/Author, edit the custom document template.
  2. Add placeholders in the form of processing instructions within the elements where you want hints to be displayed when an Author creates a document from the template. For example:
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
    <topic id="pi">
      <title><?oxy-placeholder content="Enter a title"?></title>
        <shortdesc><?oxy-placeholder content="Writing short descriptions 
             induces the writer to clarify the main thesis of the topic.
             We recommended a 50 word limit."?></shortdesc>
      <body>
        <p><?oxy-placeholder content="A paragraph element should be a self-contained
             unit dealing with one idea or point."?></p>
      </body>
    </topic>
  3. Save the template file (it should be inside your custom framework folder).
  4. Create an archive that only contains your custom framework folder (one single folder) and upload the changes to your framework to Web Author.

Result: The placeholders should now be visible in that particular custom document template when creating new documents.