Creating Content Templates
You can templates for different document types that you commonly use.
Keep these guidelines in mind when creating templates:
- You can restrict access to template configuration files to prevent unwanted changes to the templates
- You can add in variable elements and content like map metadata to the template
- You can provide internal guidance on how to use a template by including draft comment elements or conditional processing attributes in the template
- You can include any allowed elements or content in a templateNote: Linking between topics in templates results in broken links. For more information, contact a Customer Success Manager.
Templates or specializations?
Templates are based on standard DITA map and topic elements and can be created by anyone. Specializations are extensions of the standard DITA elements. If you are interested in using specializations, contact your Customer Success Manager.
Configure a Template
- In the __configuration folder in the content library, navigate to the templates folder.Note: If you don't see a __configuration folder in your content library, contact your Customer Success Manager.
- Create a new folder with your organization name, to keep your templates separate from the default templates.
- Optional: Create folders for maps and topics, depending on your template configuration.
- Create template resources:
- Modify topics and maps so they can be templates. See Add Variable Data and Warehouses to a Template.
- Make the template available in the Create New menu.
Create a Topic Template
Create a topic template with the desired structure and content.
- In the content library, in the __configuration folder:
- Click Create New and select a topic type that you want to use as a template.If you create a template for reference material such as a data-sheet, select Reference.
- Enter a title and file name.
- Click Create & Edit.
- Click Create New and select a topic type that you want to use as a template.
- Edit the topic template to include desired elements, text, or guidance.
Create a Map Template
Create a map template with the desired topics, elements, and content.
In the content library, in the __configuration
- Click Create New and select a map type that you want to use as a template.
- Enter a title and file name.
- Click Create & Edit.
- Add topics that you want to include to the map.
- Optional: Add any other elements or metadata to the map.
Add Variable Data and Warehouses to a Template
Modify the template ID, author information in the prolog element, and the template title.
- Set the template to generate random IDs for root topic elements or root map
elements.For topics, replace:
<topic id="topic-[RANDOM]">For maps, replace:
<map id="ditamap-[RANDOM]">Important: If you have IDs on elements in the body of a topic template, you need to also convert those ID values to use [RANDOM] instead of a specific numeric value.For example:
- Modify the prolog element to populate the author
information with the user that creates a new topic or map from the
<author>John Smith <firstname.lastname@example.org></author>
- Optional: Modify the template title element to use the title
entered by the user when they create a new topic or a map from the
template.Tip: Skip this step if you want to use a consistent map or topic title, such as Policy & Procedures. If you choose to skip this step, users will be prompted to enter a unique file name, but will not be able to change the title of the document from the Create new window.Replace:
<title>Policy & Procedures</title>
- For any paths to maps or topics that are not templates, for example, a warehouse map or a copyrights topic, change the relative path in the
hrefto an absolute path to its location in the database.
- In the content library, click on the map or topic in question to open the Resource Details Drawer.
- In the Overview section, click on the API Info to expand it.
- Copy the entire URI.
- Go back to the map or topic you're updating.
- Switch to the Source Editor.
- Replace the relative path in the
hrefattribute with the URI that you copied.
This is an example of a relative path to a warehouse map:
<mapref format="ditamap" href="../../../global_shared/documents/global_shared.ditamap" processing-role="resource-only"/>
This is an example of the same mapref, but we've replaced the relative path with the database URI:
<mapref format="ditamap" href="/db/organizations/myorg/repositories/master/global_shared/documents/global_shared.ditamap" processing-role="resource-only"/>Tip: The process is the same for topics. Do this only for topics that are reused or shared, for example, copyrights or legal notices.
- Save the changes.
When you create a new map or topic from a template, any reused or shared content will resolve no matter where in the repository you create the new map or topic.
Enable a Template
You enable map and topic templates so they become available in the Create New menu.
- In the __configuration folder in the content library, navigate to templates/technicalContent/topic.
- Right-click on the topic.xml file and select Download.If you're enabling a map, download map.xml from the map folder.
- Open the topic.xml file in oXygen or another editor.The topic.xml file looks like this:
<?xml version="1.0" encoding="UTF-8"?> <template> <label>Custom Topic Template</label> <instance source="custom_topic_template.dita"/> </template>
- In the
<label>element, type the template name you want listed in the Create New menu.For example, replace
<label>Custom Topic Template</label>with
- In the
instanceelement, change the
sourceattribute value to the file name of the topic or map you want to enable as a template.For example, replace
- Save the topic.xml file with a file name that matches the template file name.For example, save the file as briefing_note_template.xml
- Upload the file to the __configuration folder, in the same location in the __configuration folder as the template that you're enabling.
- Refresh your browser.
- Open the Create New menu to confirm that the new template is listed.
- Recommended: Create new topics or maps to ensure that you've configured the templates properly.