Insert Key Reference Dialog Box
This dialog box enables you to insert a key reference into a DITA topic or map. You invoke this dialog box from either the > menu choice or the associated toolbar button. If desired, you can dock this dialog in the Arbortext Editor window.
The keys included in this dialog box come from DITA maps included in the ditakeybaselist advanced preference. You can also add maps to the list for the current session through the Add/Remove button. Also, if you open a topic from the context of a map that contains key definitions, that map become the part of the key context when you open this dialog box for that topic. If the map containing your key definitions is a DITA Key Definition Map, then additional information is available for those definitions.
The Insert Key Reference dialog box contains the following options:
• Search — Enables you to filter the list of available key definitions.
As you type in this option, the contents of the key definition table are automatically filtered to match what you are typing. The search covers the contents of the Key Name, Title/Description, and Reference columns in the table. It also covers any text, including markup, in the Resource column.
• Match Case — Determines whether searches done in the Search option are case sensitive.
• Starts With — Determines whether searches done in the Search option should just match the beginning of the content in the searched columns.
• Map — Determines the map used for the key definitions in the key definition table.
The default value All means to use all of the key definitions in the current key context. If you select a specific map from the drop-down list, just the key definitions from that map appear in the key definition list.
Use this dialog box to add or remove maps from your current key context. Note that this just changes the key context from the current session. To permanently change the key context, you must modify the ditakeybaselist advanced preference.
• Key definition table – Lists the key definitions that you can insert as references in your document.
If the map containing the key definitions is a DITA Key Definition Map, then additional information is available for the definitions. If a key is defined more than once, each definition appears in its own row. If several keys are defined on one key definition, each key is listed separately in its own row.
The table contains the following columns:
◦ Key Name — Provides the name of the key.
Regular keys do not have an icon. Content reference keys are indicated by the
icon. If the key is defined in a DITA Key Definition Map and the
keysubelementid element is specified, that ID value is appended to the key name after a leading
/.
◦ Type — Provides the list of elements that can be used to reference this key.
If the key is defined in a DITA Key Definition Map and the keyreftags element is specified, the list of keys comes from that element. Otherwise, the value is Any meaning any element with a keyref element can reference the key. If the key is for a content key reference (conkeyref), the value is the name of the element to be used for the content reference followed by (conref).
◦ Title / Description — Provides a description of the key.
If the key is defined in a DITA Key Definition Map and the keydescription element is specified, the description comes from that element. Otherwise, the description comes from the content of the navtitle element, the navtitle attribute, or the linktext element in that order. Note that in case of DITA 2.0 documents the description comes from the content of the titlehint, navtitle or linktitle element, in that order, if the keydescription element is not specified.
◦ Resource — Provides either the value of the href attribute from the key definition or any text in the definition, including markup, if no href value is supplied in the key definition.
When no href value is supplied in a key definition, it is assumed the definition contains content for text replacement.
◦ Map Name — Provides the name of the map that contains the key definition.
Just the base name of the map appears in the table. If the key definition is from a map referenced from another map, what displays is the base name of the parent map followed by the base name of the referenced map in parentheses.
• Insert dropdown list — Provides a list of valid key reference elements to insert at the current cursor location.
For key references not intended for text replacement, the contents of this list are determined by the type of element in which the cursor is located. The contents of the list is also effected by whether there are a set of allowed tags in the Type column and by the value of the smartinsert advanced preference.
For key references intended for text replacement, the elements displayed in the list are determined by the value of the ditatextkeyrefs advanced preference. By default, this preference is set to off meaning that only linking elements that allow a key reference are shown in the list. If you set the preference to on, then non-linking elements that allow a key reference are also shown in the list. This enables you to insert key references intended for text replacement for those types of elements.
• Insert button — Inserts the selected key reference using the selected element into your document.
The value of the href, scope, type, and format attributes, and the link text from the key definition is used for the inserted reference.