Creating Variable Text in DITA

You may often find that you want a certain piece of text in a topic to have a different value in various circumstances. For example, if you are reusing a topic about a feature that is shared between several products, you might want to make the name of the product variable so that the correct product name is used in the manual for each product.

For example, you might have a sentence like this:

The quick-heat feature allows [product-name] to come up to temperature quickly.

You need a way to substitute the correct product name for each product.

One way to do this would be to use conditional profiling, as in this figure:

Figure: Variable content using profiling

<p>The quick-heat feature allows 
    <ph product="basic">Basic Widget</ph>
    <ph product="pro">Pro Widget</ph>
    <ph product="enterprise">Enterprise Widget</ph>
to come up to temperature quickly.</p>

In DITA, you can create variable text using keys.

One way to do this would be to provide conditional values using the product profiling attribute.

However, this approach means that you are repeating the product names over and over again everywhere the product name is mentioned. This is time consuming for authors and will create a maintenance problem if the product names change.

The alternative is to use a key reference, as in the following example:

Figure: Variable content using a key reference

<p>The quick-heat feature allows <ph keyref="product"/> to come up to temperature quickly.</p>

The key reference stands in for the name of the product. When the content is published, the current value of the key product will be inserted.

Inserting a Key Reference

To insert a key reference into a document in Oxygen XML Editor Author mode:
  1. Press Enter and select any DITA element that supports the keyref attribute.
  2. Press Alt+Enter to bring up the attribute editor.
  3. In the Name field, select keyref.
  4. In the Value field, select or enter the name of the key.

Defining a Key

In DITA, keys are defined in maps, never in topics. A DITA map that defines various values of the product key would look something like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map>
  <!-- product name -->
  <keydef keys="product" product="basic">
    <topicmeta>
      <keywords>
        <keyword>Basic Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="product" product="pro">
    <topicmeta>
      <keywords>
        <keyword>Professional Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="product" product="enterprise">
    <topicmeta>
      <keywords>
        <keyword>Enterprise Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
Note: The profiling of the names that was shown in the Figure 1 figure is now contained in the map, where it only has to occur once.

Depending on which profiling conditions are active in Oxygen XML Editor, you will see different values of the key displayed in Author mode.

Parent topic: Reuse