Variable Reuse

Variables enable you to easily reuse and update content like a product names, interface terms, or other items that might change either because they're being used in different contexts or because of external changes like rebranding.

Variable Reuse Methods

You can reuse variables by using conkeyref attributes or keyref attributes. However, we recommend reusing variables with conkeyref attributes. Whatever method you choose, use it consistently.

Table 1. Variable Reuse Methods Comparison
Variable Reuse with ConkeyrefsVariable Reuse with Keyrefs
Can be fully managed through a dedicated graphical user interface in easyDITA.Cannot be fully managed through a dedicated graphical user interface in easyDITA. You may need to use the source editor to edit DITA code.
Contained in variable warehouse topics.Contained in variable warehouse maps.
Involves conkeyref attributes.Involves keyref attributes.
Involves phrase elements.Involves keyword elements.

Localization Considerations

If you localize content or plan to localize content, keep the following considerations in mind while using variables:

  • In some languages, words change form depending on their role in the sentence. Because the text in the variables forms a part of the grammatical structure of the sentence, using a variable in sentences with different grammatical structures can introduce unintended errors in the target language.
  • You can safely use non-grammatical items for variable content. For example, it is rather safe to translate variable content like phone numbers, addresses, hours of operation, or external links.

Variable Reuse with Conkeyrefs

You reuse variables from variable warehouse topics with conkeyref attributes.

Overview

The following example shows that:
  • The “Variables Warehouse” topic is added to the deliverable “Map A” through the keydef element with the @keys attribute assigned.
    Important: Including variable warehouse topics through the keydef element with the @keys attribute assigned is necessary for the variable reuse mechanism to operate properly. By default, keydef elements are not included in the output.
  • “Variable A” is used in “Element A” in “Topic A”.
  • “Variable B” is used in “Element A” and in “Element D”. The elements are in different topics.

Example

The following examples show the variable reuse mechanism through conkeyref attributes in easyDITA. The topic editor indicates reused variables with gray background.

Figure 1. Map A.

The following example shows a map that includes “Topic A”, “Topic B” and “Warehouse Topic”. The warehouse topic contains variables.

<map id="ditamap-7326" title="Map A">
    <topicref href="topic_a.dita"/>
    <topicref href="topic_b.dita"/>
    <keydef href="warehouse_topic.dita" keys="vars"/>
</map>
Figure 2. Variable Warehouse Topic.

The following example shows a warehouse topic that includes two variables.

Figure 3. Topic A.

The following example shows a topic that references two variables from the variable warehouse topic.

Figure 4. Topic B.

The following example shows a topic that references one variable from the variable warehouse topic.

Create a Variable Warehouse Topic

Create a variable warehouse topic that contains variables for product names, interface names, etc.

Tip: We recommend grouping similar variables in dedicated variable warehouses. For example, you can keep your product name variables and interface variables in separate variable warehouses. This strategy prevents your variable warehouses from becoming cluttered and disorganized as you add new reusable elements over time.
  1. In the content library, navigate to the folder where you want to create the variable warehouse topic.
    Tip: We recommend creating variable warehouses in a dedicated folder (e.g. _variables). Keeping variable warehouses in one place, makes it easy to find and update reusable content.
  2. Create a variable warehouse topic by doing the following:
    1. Click Create New > Default Topic template .
    2. In the Title field, enter a meaningful name for the variable warehouse topic.
      Enter Interface Variables
    3. Click Create & Edit .
  3. Create a table for your variables by doing the following:
    1. Place your cursor where you want to add the table.
    2. In the toolbar, click Insert Table .
    3. In the Create Table window, select the Generate Header check box and set two columns and a few rows.
    4. Click the Ok button.
    5. Name the first column Variable and the second column ID.
    6. In the Variable column, place your cursor in a cell, and insert a phrase element.
  4. Define variables by doing the following:
    1. In the phrase element, enter the variable text.
      Remember: You must enter the variable text within the phrase element to make it reusable.
      Enter Classic Toaster.
    2. Click the phrase element and click the Attributes tab.
    3. In the id field, enter a unique, meaningful identifier for the variable and copy it.
      Enter ProductName
    4. In the ID column of the table, paste the ID value that you copied in /user-guide/reuse/variable-reuse#task-3554__substep_oqq_fys_w3b.
      Note: You fill in the ID column of the table for your convenience. The ID column of the table enables you to quickly find and copy the IDs of the corresponding variables.
      Paste ProductName
You created variable content and assigned an ID to it.
Add the variable warehouse topic to the maps that you want to use the variables in. See Add Variable Warehouse Topics to Maps.

Add Variable Warehouse Topics to Maps

Add a variable warehouse topic to a map as a keydef element to enable variable reuse through content key references (conkeyrefs).

Note: keydef elements appended to a map are not published and are not visible in the output. This is possible because the processing-role attribute value of the keydef element is set to resource-only by default.
Create a variable warehouse topic and define variables. See Create a Variable Warehouse Topic.
  1. In the content library, hover over a map and click the Dock button.
  2. While holding the Shift keyboard key, drag and drop the variable warehouse topic from the content library into the map editor pane.
  3. From the Insert drop-down menu, select Keydef .
  4. In the Keys field, enter the key name.
    You can enter vars, which is short for variables.
  5. Click Insert.
Insert content key references to variables in the variable warehouse topic that you added to the map. See Reuse Variables through Conkeyrefs.

Reuse Variables through Conkeyrefs

You reuse variables from the variable warehouse topics through phrase elements and conkeyref attributes.

Add a variable warehouse topic to a map as a keydef element. See Add Variable Warehouse Topics to Maps.
  1. Open a map with a topic in which you want to reuse a variable.
  2. Navigate to the topic that you want to insert the variable in.
  3. Place your cursor where you want to insert the variable.
  4. Open the Con/Keyref drop-down menu by pressing Cmd > Shift > K (Mac) or Ctrl > Shift > K (Windows).
  5. Do any of the following:
    • If you know the variable ID, begin entering the ID.

      easyDITA automatically highlights the closest match.

    • If you don't know the variable ID, find the variable by browsing the list.
  6. In the list, double-click the variable that you want to insert.