Variable Reuse

Variables enable you to easily reuse and update content like 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 Heretto CCMS.Cannot be fully managed through a dedicated graphical user interface in Heretto CCMS. 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 usually safe to translate variable content like phone numbers, addresses, hours of operation, or external links.

Variable Reuse with Keyrefs

You can reuse variables from variable warehouse maps with keyref attributes.

Overview

The following example shows that:
  • The “Warehouse Map” is added to the deliverable “Map A” through the mapref element with the @processing-role="resource-only" attribute assigned.
  • “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.
Reusing variables with keyrefs

Example

The following example shows the variable reuse mechanism through keyref attributes in Heretto CCMS. The Content Editor indicates reused variables with a key icon and a gray background.

Figure 1. Variable Reuse Example.
The following example shows that:
  • The “companyName” variable is used in “Topic A”
  • The “productName” variable is used in “Topic A” and “Topic B”
  • The variables are reused from “Variable Warehouse Map” through keyref attributes and keyword elements
Reusing variables with keys

Create a Variable Warehouse Map

Create a variable warehouse map 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 map.
    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 map by doing the following:
    1. Click Create New > Map.
    2. In the Title field, enter a meaningful name for the variable warehouse map.
      Enter Interface Variables

      .

    3. Click Create & Edit.
  3. Add a variable to the variable warehouse map by doing the following:
    1. In the Map Editor, right-click the map title (not the <title> tag) and select Append element > keydef.
    2. In the Required Properties dialog, in the Keys field, enter a key name and click Save.
    3. Right-click <keydef> and select Append element > topicmeta.
    4. Right-click <topicmeta> and select Append element > keywords.
    5. Right-click <keywords> and select Append element > keyword.
    6. Right-click the map title and select Edit Element XML.
    7. Change <keyword/> to <keyword></keyword>
    8. Enter the text that you want to display for that keyword in between the <keyword> and </keyword> tags.
      <keyword>Displayed Name</keyword>
  4. If needed, add more keywords by doing any of the following:
    • Repeat 3.
    • Copy, paste, and edit an existing keydef element in the Source Editor.
  5. Click Save.
Add the variable warehouse map to a deliverable map. See Add Variable Warehouse Maps to Deliverable Maps.

Add Variable Warehouse Maps to Deliverable Maps

Add a variable warehouse map to a deliverable map to enable variable reuse through keyword elements and keyref attributes.

Create a variable warehouse map and define variables. See Create a Variable Warehouse Map.
  1. In the content library, double-click a map to open it in the Content Editor.
  2. In the Content Editor, click the Open Library button.
  3. In the content library, navigate to the variable warehouse map that you want to add to the deliverable map.
  4. Drag and drop the variable warehouse map from the content library into the Map Editor.
    Tip: A line appears that indicates where the component will be added. If you drop a component on another component, a green box appears. The green box indicates that the new component will be added as a child of the component that is already in the map.
  5. In the Map Editor, click the Edit element properties button for the variable warehouse map.
  6. In the Edit Properties window, from the processing-role drop-down menu, select resource-only.
Figure 2. Appended Variable Warehouse Map
Reuse variables in the deliverable 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 Reuse Variables through Conkeyrefs.
  1. Open a map with a topic in which you want to reuse a variable.
  2. Navigate to the topic in which you want to insert the variable.
  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.

      Heretto CCMS automatically highlights the closest match.

    • If you do not know the variable ID, find the variable by browsing the list.
  6. Use your keyboard keys or mouse to select and insert a variable.