Using Keys and Key References
Arbortext Editor provides support for key based references as defined in the
Key based (indirect) addressing section of the OASIS
DITA Architectural Specification. The
Arbortext Editor user interface provides many features to assist you with both defining key definitions in your DITA maps and inserting key references in your maps and topics. In addition,
Arbortext Editor provides a specialized DITA map intended for just containing key definitions called the
DITA Key Definition Map. This map enables you to provide additional information for your key definitions.
The best practice for storing your key definitions is to have a DITA map that is dedicated to just holding key definitions. You can then use a mapref element to include the map containing your key definitions in any other DITA map as needed. It is suggested you use the DITA Key Definition Map to store your key definitions.
The Key References User Interface
The following parts of the Arbortext Editor user interface support key references:
• The Insert menu has the following choices:
◦ Key Definition — Opens the Resource Manager with the Key Definition tab active.
◦ Key Reference — Opens the Insert Key Reference dialog box.
• The Tools menu has the following choices:
◦ Keys and Key References — Opens the Keys and Key References dialog box.
◦ Find Key References — Opens the Keys and Key References dialog box displaying only the keys contained in the tag containing the cursor.
This choice is also available from the Arbortext Editor shortcut menu.
◦ Key Reference Information — Opens the Key Reference Information dialog box.
This choice is also available from the Arbortext Editor shortcut menu.
• The Markup toolbar has a
Insert Key Reference![This is an image of the Insert Key Reference toolbar button.](../../editor/editor_help/images/ditainsertkeyref.png)
button that opens the
Insert Key Reference dialog box.
• The following Resource Manager features support key references:
◦ The
Key Definition tab is available in DITA maps to help you define key definitions.
A version of this tab for modifying key definitions is available from the Modify Attributes dialog box, the Document Map, and Column view.
◦ The Keyref option is available on all Resource Manager tabs and dialog boxes, except those for content references, that enables you to enter or select a key name to insert in the keyref attribute for the reference you are creating or modifying.
◦ The Conkeyref option is available on the Resource Manager tab and dialog box for content references that enables you to enter a key name to insert in the conkeyref attribute for the reference you are creating or modifying.
◦ The Link/Xref, Content Reference, and Topic tabs and dialog boxes enable you to browse to DITA maps containing key definitions and use a selected key definition for the inserted or modified reference.
• The following dialog boxes support key references:
◦ Add/Remove Map — Enables you to add or remove maps from the list of maps providing key definitions for the
Insert Key Reference dialog box.
◦ Select Reference — Enables you to select which document to open when a referencing element has more than one defined reference target.
◦ Keys and Key References — Displays the key definitions and key references contained in the current document and any documents referenced from the current document.
Hiding the Key Reference User Interface
By default, the key reference user interface is available in Arbortext Editor. If you are not using key references in your DITA documentation, you can remove the key reference features from the user interface.
Whether the key reference user interface is available is controlled by the ditakeyrefui advanced preference. Set the value of this preference to off to remove the key reference user interface.
Establishing the Key Context
For Arbortext Editor to find the key definitions associated with key references, it must know the key context for the current document. The key context is a DITA map that contains the relevant key definitions. If the map containing the definitions is a DITA Key Definition Map, you can add additional information to the key definitions that appears in the key reference user interface. The key context for a document is determined by the settings of the ditakeycontext set option.
The ditakeycontext option is set to a single map and defines the primary key context for the current document during the current session. When a document has a key context established, it affects how Arbortext Editor handles references. For example, if an image tag has both an href and a keyref attribute defined, Arbortext Editor displays the image from the keyref attribute’s key definition. Arbortext Editor gives a key reference or content key reference precedence when there is an established key context that contains a matching key definition.
You can set the ditakeycontext explicitly, or Arbortext Editor sets it automatically in some cases. For example, if you open a document through double-clicking on a cross reference, topic reference, and so forth, the key context for the original document is applied to the newly opened document. Similarly, when you open a document from an Arbortext Editor DITA-related dialog box, the key context for the current document is applied to the opened document. If the original document is a DITA map that does not have a key context, that map becomes the key context for the opened document.
Another option that determines the key definitions available for inserting into a document is the ditakeybaselist set option. You use the ditakeybaselist option primarily to establish the list of maps used for the key definitions displayed in the Insert Key Reference dialog box and in the Resource Manager’s Keyref option. Unlike ditakeycontext, ditakeybaselist is an advanced preference, can contain multiple maps, and persists across Arbortext Editor sessions. If you have assigned a value to the ditakeybaselist and the map that is the current ditakeycontext is not in that list, the key context map is added to the beginning of the list of ditakeybaselist maps for the current session.
Using the DITA Key Definition Map
Arbortext Editor provides a specialized DITA map called the DITA Key Definition Map. This map contains additional elements that enable you to provide more information in your key definitions and is intended to be used just for storing key definitions. The extra key definition information is displayed in the key reference user interface in various places. The DITA Key Definition Map is in the New dialog box’s DITA Technical Content categories.
The key definition map adds extra elements to the topicmeta element that provide more information about the key definitions. To use these elements, you would insert a keydef element into the map, insert a topicmeta element in the keydef element and a keyinfo element in topicmeta. You can then insert whichever of the new metadata elements you would like to use inside of keyinfo. You can also use the Resource Manager’s Key Definition tab in a key definition map to add this extra information to your key definitions.
The following additional elements are available in topicmeta for regular key references:
• keyinfo — Encloses the other elements except the keytext element.
• keydescription — Contains a text description of the key.
• keysubelementid — Specifies (in the value attribute) a specific element ID to which this key should apply.
• keyreftags — Contains (in the value attribute) a list of one or more element names that should be used to reference this key.
• keytext — Specifies the variable or link text; it also specifies alternate text for images that are referenced by keys. This element is available for DITA 2.0 documents only.
Working with Content Key References
To replace content through a key reference in Arbortext Editor, you can use the conkeyref attribute on an element to set up a content key reference. As with regular key references when a content key reference has an associated definition in the key context for a document and an element has both the conref and conkeyref attributes defined, Arbortext Editor displays the content associated with the conkeyref and generally gives the key content reference precedence.
You can use a regular key definition to set up the keys for content key references. However, the DITA Key Definition Map provides some additional elements to assist you with defining key definitions for content references. Also, to include content key references in the Insert Key Reference dialog box, you must define the associated key definitions in a DITA Key Definition Map. The following additional elements are available for content key references:
• keyconrefs — Enables you to define key definitions specifically for content key references.
The element is a specialization of the keydef element. Elements with IDs inside of topics or maps that reference a key name defined with keyconrefs show up as targets for a conkeyref reference in the Insert Key Reference dialog box. The scope attribute on this element is set to local. The format attribute is set to either dita (the default) or ditamap.
This element also includes the new keyinfo element and all of it’s subelements. If you assign a value to the keysubelementid element in a keyconrefs definition, just elements with that specific ID will be available for a content key reference using that definition. Otherwise, all elements with IDs are available.
• keyforconrefs — Indicates a key definition is for a content key reference.
This element is contained in the keyinfo element. When the keyforconrefs element’s value attribute is set to true (the default), this indicates that this key definition is for a content key reference and it will be treated as such in the Insert Key Reference dialog box. This enables you to use keydef and other elements in your map to define key definitions for content key references.
Using a DITA Key Definition Map, you can set up your content key definitions so that either a single element is available for a content key reference or all elements with IDs are available. To make a single element available for a conkeyref reference in the Insert Key Reference dialog box, you must define it in a DITA Key Definition Map using the following markup:
• The href attribute on the key definition must point to the topic or map that contains the element.
The element’s ID must not be included in the href.
• The keysubelementid element’s value attribute must specify the ID of the element.
• The keyreftags element’s value attribute must contain the name of the element that has the specified ID, prefixed with the string conkeyref:.
For example, the following key definition adds the ph element with the ID custom in the topic strings.dita to the Insert Key Reference dialog box as a conkeyref target:
<keydef keys=”strings” href=”strings.dita”>
<topicmeta>
<keyinfo>
<keydescription>Description of the “custom” element</keydescription>
<keysubelementid value=”custom”/>
<keyreftags value=”conkeyref:ph”/>
</keyinfo>
</topicmeta>
</keydef>
To make all elements with IDs available in a map or topic for a conkeyref reference in the Insert Key Reference dialog box, you must also define that in a DITA Key Definition Map. You can define that markup in one of the following ways:
• Use the keyconrefs element to make the key definition.
For example:
<keyconrefs href=”strings.dita” keys=”strings”/>
• Use any valid element for defining a key definition with a keyforconrefs element inside of the keyinfo element in the topicmeta element.
For example:
<keydef href=”strings.dita” keys=”strings”>
<topicmeta>
<keyinfo>
<keyforconrefs/>
</keyinfo>
</topicmeta>
</keydef>
Inserting Text with Key References
You can also use regular key references to insert text into your documents. Many DITA elements have the keyref attribute. You can include text in your key definitions to insert into these elements, when the element is empty and has a key reference set. The element must be empty to be used for text insertion. For example, you could have the following element in your document:
<ph keyref="product-name"></ph>
The key references the following key definition:
For DITA 1.3 | For DITA 2.0 |
<keydef keys="product-name"> <topicmeta> <keywords> <keyword>Acme Product</keyword> </keywords> </topicmeta> </keydef> | <keydef keys="product-name"> <topicmeta> <keytext>Acme Product</keytext> </topicmeta> </keydef> |
When you publish the document, the following text is inserted in the ph element:
<ph>Acme Product</ph>
You can also include markup with the text you want to insert. For example, when the key references the following key definition:
<keydef keys="product-name">
<topicmeta>
<keywords>
<keyword><i>Acme Product</i></keyword>
</keywords>
</topicmeta>
</keydef>
The following text is inserted in the document:
<ph><i>Acme Product</i></ph>
In addition to inserting text, you can also turn non-linking elements into linking elements and vice versa by including an href attribute in your key definition. For example, consider the following key definitions:
<keydef keys="product-name" href="acme.dita">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="product-name-no-link">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
These key definitions are referenced by the following elements in your document:
<ph keyref="product-name"></ph>
<xref keyref="product-name"></xref>
<ph keyref="product-name-no-link"></ph>
<xref keyref="product-name-no-link"></xref>
When the document is published, the following text is inserted into your document:
<ph>
<xref href="acme.dita">Acme Product</xref>
</ph>
<xref href="acme.dita">Acme Product</xref>
<ph>Acme Product</ph>
<xref>Acme Product</xref>
Note that when the key definition has an href assigned, the element into which the text is inserted becomes a linking element. When it does not have an href assigned, even a linking element such as xref does not contain a link. This linking behavior applies even if the element referencing the key definition contains content and cannot be used for text insertion. For example, consider when the following element references the key definition above:
<ph keyref="product-name">New Acme Product</ph>
In this case, the key reference just makes the element a linking element and does not insert the text in the key definition when the document is published:
<ph>
<xref href="acme.dita">New Acme Product</xref>
</ph>
The text to be inserted from a key definition is determined in the following order of precedence in case of DITA 1.3 documents:
1. The contents of the first keyword element in the keywords element in the topicmeta element of the key definition
2. The contents of the first term element in keywords element in the topicmeta element of the key definition
3. The contents of the linktext element in the topicmeta element of the key definition
4. The contents of the navtitle element in the topicmeta element of the key definition
5. The contents of the navtitle attribute of the key definition
For example, the following key definition contains text in more than one of the possible areas for text insertion:
<keydef keys="product-name" navtitle="New Acme Product">
<topicmeta>
<keywords>
<keyword>Acme Product</keyword>
</keywords>
</topicmeta>
</keydef>
The text to be inserted from a key definition is determined in the following order of precedence in case of DITA 2.0 documents:
1. The contents of the first keytext element in the topicmeta element of the key definition
2. The contents of the first titlealt element with title-role attribute value set to ‘linking’ or the first linktext element in the topicmeta element of the key definition
3. The contents of the first titlealt element with title-role attribute value set to ‘navigation’ or the first navtitle element in the topicmeta element of the key definition
For example, the following key definition contains text in more than one of the possible areas for text insertion:
<keydef keys="product-name">
<topicmeta>
<keytext>Acme Product</keytext>
<navtitle>New Acme Product</navtitle>
</topicmeta>
</keydef>
In this case, the text inserted for a key reference is the contents of the keytext element since it has a higher precedence than the contents of the navtitle element.
The following elements are special cases for text insertion:
• link
The link element does not contain text directly. It does contain optional linktext and desc elements that can contain text. In this case, if you have linktext and desc elements in the topicmeta element of the key definition, those elements are inserted into the link element when the document is published.
• image
The image element contains an alt element that provides a text description of the image. If an empty image element has a key reference to a key definition that contains text for text insertion, that text is inserted in the image as an alt element during publishing.
• Elements that do not allow text content
Some DITA elements, such as longdescref, contain the keyref attribute but do not allow text content. These elements cannot be used for text insertion through key references.
The Arbortext Editor user interface provides the following features to support inserting text with key references:
• The
Key Reference Information dialog box provides a
Text option that displays the text content, including any markup, provided in the key definition.
• The
Insert Key Reference dialog box displays the text content for a key definition, including markup, in the
Resource column.
Also, when the ditatextkeyrefs advanced preference is set to on, non-linking elements that allow a key reference are shown in the Insert drop-down list.
• Empty elements with a key reference assigned display the name of the key reference enclosed in parenthesis when editing a DITA document:
Note that this is only supported for non-linking elements in the default stylesheets for DITA documents. The key reference name only appears when editing documents in Arbortext Editor. It does not appear when the document is published.