Edit online

Customizing Document Templates

Oxygen XML Editor allows you to customize certain aspects of built-in or custom document templates. For example, you can customize the icons or specify a prefix/suffix that will be used for the proposed file name in the New document wizard.

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. 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 must 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.
      Important: If you created a new template and chose to use a custom directory for the new template (in step 2 of the new template procedure), make sure that the path to the icons is relative to that directory.
  2. Save the properties file in the same directory as your custom template.
  3. Open the new file wizard (File > New) and you should see your custom icons next to the document template in the appropriate folder.

Add a Prefix or Suffix to File Names for a Document Template

You can use a properties file for each document template to add a prefix or suffix to the file name that is proposed in certain dialog boxes when you create a new file from that template. This applies to the following new document dialog boxes:
  • The new document dialog box that appears when you click the New button on the toolbar (or File > New). The prefix or suffix is added to the name of the file in the Save as field.
  • The new document dialog box that appears when you select New > File from the contextual menu in the Project view. The prefix or suffix is added to the name of the file in the File name field.
  • For DITA files, it also applies to the new document dialog box that appears when you select Append Child > New, Insert Before > New, or Insert After > New from the DITA Maps Manager. The prefix or suffix is added to the name of the file in the Save as field.
  • For DITA files, it also applies to the Fast Create Topics dialog box that you can use to create multiple skeleton topics at once.
To add a prefix or suffix to the file names for a document template, follow these steps:
  1. Create a new properties file or edit an existing one.

    • If you create a new properties file, use the same name as the template file except with a .properties extension (for example, MyTemplate.properties). This properties file specifies the prefix/suffix that will be used to propose the file name in the new file wizards.

      When defining the prefix/suffix, the properties file should look something like this:
      type=general
filenamePrefix=prod_
filenameSuffix=_test
      Important: For DITA files, the type property must be set to dita. For all other types of files, set it to general.
    • If you edit an existing template, simply define the prefix/suffix as specified above.
  2. Save the properties file in the same directory as the document template.
  3. Open the new document wizard (using the methods described above) and when you select the appropriate template, you should see your prefix or suffix in the file name that is proposed in that dialog box.
Note: The filenamePrefix and filenameSuffix properties can also have editor variables that do not require user interaction (i.e. editor variables that have ${ask()} and ${answer()} as values cannot be used).

Configure the Displayed Names for Document Templates

To change the name that is displayed for a document template, use the following procedure:
  1. Create a new properties file or edit an existing one. If you create a new properties file, use the same name as the template file except with a .properties extension (for example, MyTemplate.properties).
  2. Add a displayName property in the properties file:
    displayName=My Template Name
    Tip: The names for framework-specific document templates (such as DITA Topic or DocBook Article, as you would see in the Framework templates folder in the New file wizard) can be translated via the internationalization support. In this case, the properties file should contain something like:
    displayName=${i18n(tag)}

    where tag refers to an entry in the translation.xml file for that specific framework (for example, OXYGEN_INSTALL_DIR/frameworks/dita/i18n/translation.xml for DITA).

  3. Save the properties file in the same directory as the document template.
  4. Open the new file wizard (File > New) and you should see the new name for the template.

Adding Placeholders or Hints in a Document Template

If a document template contains empty elements, it may not be clear to the Author what should be inserted in them. 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 document template to provide authors with hints, follow this procedure:
  1. Edit the 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>
    Important: The elements that contain the placeholder processing instructions cannot contain other content/text, not even whitespace used for indentation. Otherwise, the placeholder will not be rendered properly.
  3. Save the template file.
  4. Use the New document wizard to create a new document using your customized template and you should see the hints in the open document.

Resources

To see a visual demonstration of how to customize document templates and to get more ideas for other advanced customization possibilities, watch our Webinar: Working with DITA in Oxygen - Customizing the Editing Experience.