Creating Content Templates

You can templates for different document types that you commonly use.

Tip: For example, if all your policy documents follow a similar format, it may be a good idea to create a template that contains the basic elements and structure used in that document type. By default, every user in your organization can use templates to create content.

Guidelines

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 template
    Note: Linking between topics in templates results in broken links. For more information, contact a Customer Success Manager.

Examples

Figure 1. Change Request Topic Template
topic template for change requests
Figure 2. Briefing Note Topic Template
topic template for briefing notes
Figure 3. Policy Map Template
map template for policy guides

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

Implementing templates in Heretto CCMS requires initial configuration.
  1. 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.
  2. Create a new folder with your organization name, to keep your templates separate from the default templates.
  3. Optional: Create folders for maps and topics, depending on your template configuration.
  4. Create template resources:
  5. Modify topics and maps so they can be templates. See Add Variable Data and Warehouses to a Template.
  6. Make the template available in the Create New menu.

Create a Topic Template

Create a topic template with the desired structure and content.

  1. In the content library, in the __configuration folder:
    1. 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.
    2. Enter a title and file name.
    3. Click Create & Edit.
  2. Edit the topic template to include desired elements, text, or guidance.
    Figure 4. Topic Template Example.

    The following template includes a table element with labels and guidance text in the draft comment element.

    topic template for change requests
Modify the template content. See Add Variable Data and Warehouses to a Template.

Create a Map Template

Create a map template with the desired topics, elements, and content.

  1. In the content library, in the __configuration folder :
    1. Click Create New and select a map type that you want to use as a template.
    2. Enter a title and file name.
    3. Click Create & Edit.
  2. Add topics that you want to include to the map.
  3. Optional: Add any other elements or metadata to the map.
Update the map to have the template format. See Add Variable Data and Warehouses to a Template.

Add Variable Data and Warehouses to a Template

Modify the template ID, author information in the prolog element, and the template title.

Open a map template or topic template in the Source Editor. See Edit the Topic XML Code or Edit the Map XML Code.
Configure variable data
  1. Set the template to generate random IDs for root topic elements or root map elements.
    For topics, replace:
    <topic id="topic-3460">

    with:

    <topic id="topic-[RANDOM]">
    For maps, replace:
    <map id="ditamap-3981">

    with:

    <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:
    • <section id="section-[RANDOM]">
    • <table id="table-[RANDOM]">
  2. Modify the prolog element to populate the author information with the user that creates a new topic or map from the template.
    Replace:
    <author>John Smith &lt;john.smith@acme.com&gt;</author>

    with:

    <author>[CURRENT_USER_FIRSTNAME][CURRENT_USER_LASTNAME]&lt;[CURRENT_USERNAME]&gt;</author>
  3. 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 &amp; Procedures</title>

    with:

    <title>[REQUESTED_FILE_NAME_WITHOUT_EXTENSION]</title>
Add warehouses or other reusable content
  1. 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 href to an absolute path to its location in the database.
    1. In the content library, click on the map or topic in question to open the Resource Details Drawer.
    2. In the Overview section, click on the API Info to expand it.
    3. Copy the entire URI.
      API info section
    4. Go back to the map or topic you're updating.
    5. Switch to the Source Editor.
    6. Replace the relative path in the href attribute 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.
    7. 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.

  1. In the __configuration folder in the content library, navigate to templates/technicalContent/topic.
  2. Right-click on the topic.xml file and select Download.
    If you're enabling a map, download map.xml from the map folder.
  3. 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>
  4. 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 <label>Briefing Note</label>
  5. In the instance element, change the source attribute value to the file name of the topic or map you want to enable as a template.
    For example, replace <instance source="custom_topic_template.dita"/> with <instance source="briefing_note_template.dita">
  6. 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
  7. Upload the file to the __configuration folder, in the same location in the __configuration folder as the template that you're enabling.
  8. Refresh your browser.
  9. Open the Create New menu to confirm that the new template is listed.
  10. Recommended: Create new topics or maps to ensure that you've configured the templates properly.