Variable Reuse with Conkeyrefs

Content key references (conkeyref) enable you to reuse variables defined in DITA topics and added to a variable warehouse map.

This example shows that:

The deliverable Map A contains the Variable Warehouse Map with warehouse topics. The warehouse topics contain variables with the id attribute assigned to them. The warehouse topics are added to the Variable Warehouse Map through the keydef element element. Both the id and keys attributes are necessary to reuse content with conkeyrefs.

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 Heretto CCMS. In the Content Editor, reused variables are indicated by a gray background with a key icon above.

Figure 1. Variable Warehouse Map.

This Variable Warehouse Map contains a Product Names Variables topic added to the map with a keydef element and the keys attribute defined.

<map id="ditamap-4622">
    <title>Variable Warehouse Map</title>
    <keydef href="Product_Names_Variables.dita" keys="varsProductNames"/>
</map>

Figure 2. Map A.

This example shows a map that includesTopic A,Topic BandVariable Warehouse Map. The warehouse map contains topics with variables.

<map id="ditamap-6720">
    <title>Map A</title>
    <topicref href="Topic_A.dita"/>
    <topicref href="Topic_B.dita"/>
    <mapref format="ditamap" href="../_Global_Shared/Variables/Variable_Warehouse_Map.ditamap" processing-role="resource-only"/>
</map>

Figure 3. Variable Warehouse Topic.
This example shows a warehouse topic that includes two variables.

Conkeyref example — Figure 4. Topic A.
The following example shows a topic that references two variables from the variable warehouse topic.

Create a Variable Warehouse Topic

Create a variable warehouse topic that contains variables for a group of variables like product names or interface component names.

Tip:

We recommend grouping similar variables in dedicated variable warehouses. For example, keep your product name variables and interface variables in separate variable warehouses. This strategy prevents your variable warehouses from becoming very large, cluttered, and disorganized as you add new reusable elements over time.

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, for example _variables in the _Global_Shared folder. Keeping variable warehouses in one place, makes it easy to find and update reusable content.

Create a variable warehouse topic

Click Create New > Topic.
In the Title field, enter a meaningful name for the variable warehouse topic.
Enter Interface Variables
Click Create & Edit.

Create a table for your variables

Place your cursor where you want to add the table.
In the toolbar, click Insert Table .
In the Create Table window, select the Generate Header check box and set two columns and a few rows.
Click the Ok button.
Name the first column Variable and the second column ID.
In the Variable column, place your cursor in a cell, and insert a phrase element.

Define variables

In the phrase element, enter the variable value.

Remember: You must enter the variable value within the phrase element to make it reusable.

Enter Classic Toaster.
Click the phrase element and click the Attributes tab.
In the id field, enter a unique, meaningful identifier for the variable and copy it.
Enter ProductName.
In the ID column of the table, paste the ID value that you copied.

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. Both the phrase element and the ID added to it make your variable content reusable.

Create a variable warehouse map. See Create a Warehouse Map with Conkeyrefs.

Create a Warehouse Map with Conkeyrefs

Create a variable warehouse map for your variable warehouse topics that contain content key references (conkeyref) for product names, interface names, and more.

Create a variable warehouse topic and define variables. See Create a Variable Warehouse Topic.

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, for example _variables in the _Global_Shared folder. Keeping variable warehouses in one place, makes it easy to find and update reusable content.

Create a variable warehouse map

Click Create New > Map.
In the Title field, enter a meaningful name for the variable warehouse map.
Enter Product Name Variables
.
Click Create & Edit.

Add a variable warehouse topic to the map

A gif that presents how to add a variable warehouse topic to a map

While holding the Shift key, drag and drop the variable warehouse topic from the Content Library into the map tree pane.
From the Insert drop-down menu, select keydef.
In the Keys field, enter a key.
Enter varsProductNames, where vars is short for variables.
Click Insert.
If needed, add more warehouse topics.

Add the variable warehouse map to a deliverable map. See Add a Warehouse Map with Conkeyrefs to a Deliverable Map.

Add a Warehouse Map with Conkeyrefs to a Deliverable Map

You can add a variable warehouse map to a deliverable map to ensure that every time you open the deliverable map, variables get resolved based on that warehouse map. This is a good approach for deliverable maps for which variables should always resolve to the same values.

If you do not want to add your warehouse maps to your deliverable maps, you can skip this procedure and set your warehouse maps as context maps. See Context Maps.

Dragging and dropping a variable map on a deliverable map and setting the processing-role attribute to resource-only

Create a variable warehouse map. See Create a Warehouse Map with Conkeyrefs.

In the Content Library, double-click a map to open it in the Content Editor.
In the Content Editor, click Open Library.
In the Content Library, navigate to the variable warehouse map that you want to add to the deliverable map.
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.
In the Map Editor, click Edit element properties for the variable warehouse map.
In the Edit Properties window, from the processing-role drop-down menu, select resource-only.

You added a variable map to a deliverable map as a resource-only resource which ensures that it will resolve variables but will not publish to outputs.

<map id="ditamap-6720">
    <title>Deliverable Map</title>
    <topicref href="Topic_A.dita"/>
    <topicref href="Topic_B.dita"/>
    <mapref format="ditamap" href="../_Global_Shared/Variables/Variable_Warehouse_Map.ditamap" processing-role="resource-only"/>
</map>

Add conkeyrefs to your content. See Reuse Variables through Conkeyrefs.

Reuse Variables through Conkeyrefs

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

Ensure a variable warehouse map is available as the source of variables. You can achieve that by either adding a warehouse map to your deliverable map or by setting a context map in the Content Editor.

Add a variable warehouse topic to a map as a keydef element. See Add a Warehouse Map with Conkeyrefs to a Deliverable Map.
Set a context map. See 2.

Open a map with a topic in which you want to reuse a variable.
Optional: Set a context map as the source of your variables.
This step is required only if you are working in an individual topic or a map that doesn't contain a variable warehouse map.
1. In the top-left corner, from the Context menu, select Select a context map.
2. Navigate to and select a map. Click Select.
Place your cursor where you want to insert the variable.
Open the Con/Keyref drop-down menu by pressing Cmd > Shift > K (Mac) or Ctrl > Shift > K (Windows).
In the Con/Keyref field, start typing the variable key, ID, or content.
Use your keyboard keys or mouse to select and insert a variable.

Under maintenance

Heretto Help