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 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>
<ph product="enterprise">Enterprise 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 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.
To insert a key reference into a document in Oxygen XML Editor plugin Author mode, follow these steps:
- Press Enter and select any DITA element that supports the
keyrefattribute. - Select
Edit
Attributes from the contextual menu to bring up the attribute editor.
- In the Name field, select
keyref. - In the Value field, select or enter the name of the
key.
Note
Additionally, if you have a need for reusing the key reference pattern while editing your documentation, you could add that pattern to a code template so that it appears in your list of content completion proposals.