Templates

You can create map templates and topic 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 topic templates and map 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
Figure 2. Briefing Note Topic Template
Figure 3. Policy Map Template

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 easyDITA requires initial configuration.

Note: Jorsek provides professional services for advanced template development. For more information, contact a Customer Success Manager.
  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. Optionally, 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.
    Important: This step is performed by your Customer Success Manager.

Create a Topic Template

Create a topic template with the desired structure and content.

  1. In the __configuration folder in the content library, do the following:In your content library, do the following:
    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, guidance text in the draft comment element, and labeled examples to show how to complete the topic.

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 __configuration folder in the content library, do the following:
    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. Open the topic or map that you're referring to in a separate window or tab.
    2. Open the Properties tab.
    3. In the API Info area, copy the entire URI.
    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.

Once you've created all of your templates, contact your Customer Success Manager to have them added to the Create New menu.

Enable a Template

You enable map and topic templates by contacting your Customer Success Manager.