Customizing Document Templates

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:

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 will specify the paths to the icons that will be used in the new file wizard. You can find some examples in the templates directory of the Oxygen XML Developer installation directory to help you get started.
  When defining the icons, the properties file should look like this:
```
type=general
smallIcon=../icons/Article_16.png
bigIcon=../icons/Article_48.png
```
  Important: 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. 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.
  
  Note: 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 the path to the icons is relative to that directory.
- If you edit an existing template, simply define the icon paths as specified above.
Save the properties file in the same directory as the document template.
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.

To add a prefix or suffix to the file names for a document template, follow these steps:

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 will specify 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 needs to 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.
Save the properties file in the same directory as the document template.
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.

Configure the Displayed Names for Document Templates

To change the name that is displayed for a document template, use the following procedure:

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).
Add a displayName property in the properties file:
```
displayName=myTemplateName
```
Tip: The names for framework-specific document templates (such as DITA Topic or DocBook Article as you would see in the Framework templates section 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).
Save the properties file in the same directory as the document template.
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

Document templates sometimes 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 document template to provide authors with hints, follow this procedure:

Edit the document template.

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="Please give 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>

Save the template file.
Use the New document wizard to create a new document using your customized template and you should see the hints in the opened document.