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 the “Element D”. The elements are in different topics.

Example

The following example shows the variable reuse mechanism through keyref attributes in easyDITA. The topic editor indicates reused variables with 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

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 > Default 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 and select Append element > Empty > 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 > Empty > topicmeta.
    4. Right-click <topicmeta> and select Append element > Empty > keywords.
    5. Right-click <keywords> and select Append element > Empty > 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.
  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, hover over a map and click the Dock button.
  2. In the content library, navigate to the variable warehouse map that you want to add to the deliverable map.
  3. 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.
  4. From the dialog, select mapref and click Insert.
  5. Right-click the variable warehouse map and select Edit element attributes .
  6. In the Edit Properties window, from the processing-role drop-down menu, select resource-only .
  7. Click Save .
Figure 2. Appended Variable Warehouse Map
Reuse variables in the deliverable map. See Reuse Variables through Keyrefs.

Reuse Variables through Keyrefs

You reuse variables from the variable warehouse maps through keyword elements and keyref attributes.

Add a variable warehouse map to a deliverable map. See Add Variable Warehouse Maps to Deliverable 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:
    • Begin entering the variable @keys attribute value.

      easyDITA automatically highlights the closest match.

    • Find the variable by browsing the list.
  6. In the list, double-click the variable that you want to insert.