Edit online

Working with 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 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 Author Author mode, use one of the following methods (the method you choose simply depends on which Oxygen XML Author 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 Author 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 Author 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.