home

Heretto CCMS

Heretto CCMSHeretto Deploy APIHeretto PortalRelease Notes
Heretto CCMSHeretto Deploy APIHeretto PortalRelease Notes

Gretyl's Portal

Heretto Help

Show Contents

Show Page Sections

thumbnailHeretto CCMS

Reuse

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 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 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.
Reusing variables with conkeyrefs

Example

The following examples show the variable reuse mechanism through conkeyref attributes in Heretto CCMS. The Content 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>
Conkeyref reuse - map structure
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.

Conkeyref example
Figure 4. Topic B.

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

Conkeyref example

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 4.c.
      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, right-click a map and select 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.

      Heretto CCMS 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.

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.
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 gray background.

Figure 5. 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 > 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, right-click a map and select 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.
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.

      Heretto CCMS 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.

Last updated: October 3, 2023

Footer Section

Our Support Team is here to help

Submit a support request or check the status of your existing requests. You can also email us.

Contact Support Team

Love this help site?

You can have one, too! Sitting on top of the Heretto CCMS, our team can build a tailored portal that will delight your customers. Meet with our team to learn more.

Connect with us

Explore

Integrations

Video Tutorials

Learning DITA

Company

About Us

Contact Us

heretto.com

Legalities

Legal

Privacy Policy

Terms of Use

© 2023 Heretto Intellectual Property. All rights reserved.

Legal

Privacy Policy

Terms of Use

About Us