Defining a variable in a topic map

You can use a topic map to define variables and give them the necessary values.

(This procedure is based on the Tridion Docs database repository and Oxygen XML editor. Other tools have similar functionality.)

Prerequisites

You have all the tools available, and the necessary rights to develop new content. A suitable folder is available in the database structure.

Context

The topic map you will make must only be used to define variables. You cannot use the same topic for both variables and regular topics and other maps.

You can make a new library in one of the following ways:

You can duplicate an existing topic map and change the variable definitions and/or the values.

This existing topic map already contains the correct variables, but they have the wrong values.
You can define the variables using a topic map template.

The template contains predefined variables, but not necessarily the variables you need. You also need to assign the correct values.
You can create a new topic map from scratch and type in the necessary elements and attributes manually.

This topic map is empty.

In the procedures, descriptions and examples I use the <keyword> element. In many DITA systems, you can also use other elements. The elements must be defined in the system files that control the publishing system's functionality. Check with your system supplier for more information about this.

I recommend that you standardize the use of the <keyword> element for variables. Although it is permitted to use other elements, it is easier to be consistent. This consistency increases understanding in the team and facilitates maintenance. Especially for new users, it will be easier to identify which elements are variables and which are not.

Tip

To identify the topic map I use to define variables, and make it easier to find, I refer to it as a "keymap". This is not a standard DITA designation. In your database system, I suggest that you establish "Keymap" as a map type in your metadata. Unique identification makes the topic map easier to find.

Procedure

From the editor's main menu, select Tridion Docs ➜ Browse repository.
In the database structure, navigate to the folder where you want to establish the new topic map.
To duplicate an existing topic map:
1. Right-click on one of the existing topic maps and select Duplicate.
  A copy of the existing topic map is established.
2. Right-click on the new topic map and select Properties.
  Make sure you do this with the new topic map! You must not change the old!
3. In the dialogue box that opens, fill in all relevant fields with metadata.
  
  Follow the rules for metadata. Identifiy the new topic map so that it is easy to see that it is used to define variables.
4. Click OK.
5. Select the new topic map, then right-click and select Check out.
6. Assign the new values inside the <keyword> elements.
  
  The tags look like this:
```
<keydef keys="VARIABLE">
  <topicmeta>
    <navtitle>
      <keywords>
        <keyword>VALUE</keyword>
      </keywords>
    </navtitle>
  </topicmeta>
</keydef>
```
7. Select Tridion Docs ➜ Check in when you have finished.
To make an new topic map from a template:
1. On the toolbar on the right side, click the green + symbol to bring up relevant templates.
2. Select a template.
3. In the dialogue box that opens, fill in all relevant fields with metadata.
  
  Follow the rules for metadata. Identifiy the new topic map so that it is easy to see that it is used to define variables.
4. Click OK.
5. Select the new topic map, then right-click and select Check out.
6. Change the relevant variable definitions by altering the keys attributes and providing new values inside the <keyword> elements.
  
  The tags look like this:
```
<keydef keys="VARIABLE">
  <topicmeta>
    <navtitle>
      <keywords>
        <keyword>VALUE</keyword>
      </keywords>
    </navtitle>
  </topicmeta>
</keydef>
```
7. Select Tridion Docs ➜ Check in when you have finished.
To make an new topic map from scratch:
1. On the toolbar on the right side, click the green + symbol to bring up relevant templates.
2. Select an empty topic map template.
3. In the dialogue box that opens, fill in all relevant fields with metadata.
  
  Follow the rules for metadata. Identifiy the new topic map so that it is easy to see that it is used to define variables.
4. Click OK.
5. Select the new topic map, then right-click and select Check out.
6. Add a <keydef> element.
7. Build the structure as shown below.
8. Define the variable by setting the keys attribute and providing the requested value inside the <keyword> element.
  
  The tags look like this:
```
<keydef keys="VARIABLE">
  <topicmeta>
    <navtitle>
      <keywords>
        <keyword>VALUE</keyword>
      </keywords>
    </navtitle>
  </topicmeta>
</keydef>
```
9. Repeat (f), (g) and (h) to define additional variables.
10. Select Tridion Docs ➜ Check in when you have finished.

Tip

Consider building a modular system with variable definitions. This allows reuse of definitions and values, and provides a high degree of consistency.

These pages only explain how variables are used in DITA publishing. If you want additional explanations about the principle of variables, see under Methodology and especially Using variables in the text.

All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.

The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.

Defining a variable in a topic map

You can use a topic map to define variables and give them the necessary values.

On this page

Prerequisites

Context

Tip

Procedure

Tip