Working with Variable Text in DITA
Edit online

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 the following example:
<p>The quick-heat feature allows 
    <ph product="basic">Basic Widget</ph>
    <ph product="pro">Pro Widget</ph>
to come up to temperature quickly.</p>

Creating Variable Text Using Keys

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.

Creating Variable Content Using a Key Reference

The alternative is to use a key reference, as in the following example:
<p>The quick-heat feature allows <ph keyref="product"/> 
   to come up to temperature quickly.</p>
The definition of the key reference determines the name of the product:
<keydef keys="product" product="basic">
    <topicmeta>
      <keywords>
        <keyword>Basic Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>
  <keydef keys="product" product="pro">
    <topicmeta>
      <keywords>
        <keyword>Pro Widget</keyword>
      </keywords>
    </topicmeta>
  </keydef>

When the content is published, the current value of the key product will be inserted.

Inserting a Keyref

To insert a key reference into a document in Oxygen XML Editor plugin Author mode, use one of the following methods:
  • DITA Reusable Components View Method

    Use the DITA Reusable Components view to insert a variable reference to the defined key.

  • Code Template Method

    Add the source code pattern of the defined key to a code template so that it appears in the list of proposals in the Content Completion Assistant.

  • Edit Attributes Method
    Manually insert the keyref attribute using the attributes editor as follows:
    1. Press Enter and select any DITA element that supports the keyref attribute.
    2. Select Edit Attributes from the contextual menu to bring up the attributes editor.
    3. In the Name field, select keyref.
    4. In the Value field, select or enter the name of the defined key.
  • Text Mode Method

    If you are using Text mode, when you insert a keyref attribute, after you enter the first quote (keyref="), the Content Completion Assistant will list all the defined keys that you can select from. Note that this only works for local files.