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 a 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 to provide conditional values using the product profiling attribute, 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>

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:
<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 value defined in the product key will be inserted for each product.

Inserting a Keyref

To insert a defined key reference into a document in Oxygen XML Editor Author mode, use one of the following methods (the method you choose simply depends on which Oxygen XML Editor feature you prefer):
  • DITA Reusable Components View Method

    Use the DITA Reusable Components view to insert a variable reference to the defined key. For example, in the Keys tab, find a key defined as a variable and double-click it. Oxygen XML Editor will insert the variable as a <ph> element with a @keyref attribute that references the specified 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. For example, the code pattern could be something like <ph keyref="product"/> for defined product key.

  • Reuse Content Dialog Box Method

    Use the Reuse Content action on the main toolbar to open the Reuse Content dialog box. Use the Key option to select a key that is defined as a variable (key reference to metadata) and Oxygen XML Editor will insert the variable as a <ph> element with a @keyref attribute that references the specified key.

  • Manual Method
    Manually insert the keyref attribute using the attributes editor as follows:
    1. Press Enter and select a DITA element (for example, <ph>) that supports the keyref attribute.
    2. Select Edit Attributes from the contextual menu (or simply press Alt+Enter) 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.