Help > DITA Authoring Overview > DITA Support User Interface > Resource Manager > Key Definition Tab
  
Key Definition Tab
The Key Definition tab enables you to insert key definitions into DITA maps. If you select the Insert > Key Definition menu choice and the Resource Manager is not already open, the Resource Manager opens with the Key Definition tab active. This tab is available in the Resource Manager when you are editing a map or a specialization of a map. The setting of the ditakeyrefui advanced preference also determines whether this option is available in the Resource Manager.
The Key Definition tab has two different states. The first state is for inserting key definitions for local documents. The second state is for inserting key definitions to documents on the Internet. Also, the type of DITA map you are editing determines which options are available on the tab. If you are editing a DITA Key Definition Map, more options are available.
Options for Inserting Key Definitions to Local Documents
For inserting key definitions to local documents, the Key Definition tab contains the following options:
• Look in — Determines the location of the content displayed in the Resource Manager browser.
Select a location from the drop-down list. This field always contains the location currently available in the browser. Double-clicking on a folder in the browser causes that folder to be displayed in the Look in field. If you select The Web in this list, the Key Definition tab changes to the state for inserting key definitions to Internet documents.
The list contains a Favorite LocationsThis is an image of a yellow star. choice. Selecting this choice moves the location displayed in the browser to the Favorite Locations node where there is a list of the favorite locations you have saved.
The list also contains a HistoryThis is an image of a folder with a blue arrow superimposed pointing backwards. choice. Selecting this choice moves the location displayed in the browser to the History node where there is a list of all the locations you have visited in the current session.
• Menu button This is an image of a document. — Displays a menu that contains the following options:
◦ Open (suffixed with Document) — If you have a document selected in the browser, opens that document in a new window.
Selected XML, DITA, SGML, and HTML documents open in a new Arbortext Editor window. Other types of documents or graphics open in the associated application. For example, a graphic opens in your default graphics application.
◦ Clear History — Clears the list of visited locations from the History node in the browser.
This choice is only available when the History node is selected.
◦ Add to Favorites — Adds the selected location to the Favorite Locations list.
This choice is only available when a file system folder, content management system (CMS) folder, or similar location is selected in the browser.
◦ Remove from Favorites — Removes the selected location from the Favorite Locations list.
This choice is only available when an item in the Favorite Locations list is selected.
◦ Move Up — Moves an item in the Favorite Locations list up one level in the list.
This choice is only available when an item in the Favorite Locations list is selected.
◦ Move Down — Moves an item in the Favorite Locations list down one level in the list.
This choice is only available when an item in the Favorite Locations list is selected.
◦ Export Favorites — Opens the Save As dialog box where you can save the list of your current favorite locations in an XML file.
This choice is only available when the Favorite Locations node is selected in the browser. This option saves your favorites in an XML file that can then be imported as a list of favorites using the Import Favorites menu choice. Do not modify this XML file, as it is just intended for saving a list of favorites.
◦ Import Favorites — Opens the Open dialog box where you can select an XML file containing an exported Resource Manager favorites list.
This choice is only available when the Favorite Locations node is selected in the browser. This option enables you to import as a list of favorites that were exported using the Export Favorites menu choice.
After you select a file in the Open dialog box and click Open, another dialog box opens asking whether to Merge with or replace current favorites list? Click Merge to have locations in the imported list that are not already in your current list added to your favorites list. Click Replace to have your current favorites list completely replaced by the imported list.
◦ Check Out and Edit — Opens the selected CMS object in Arbortext Editor for editing.
If the object is not checked out, the Resource Manager checks out (locks) the object for you. You have the option to check out any dependant objects in the same operation. This menu choice is only available for PTC Server connection objects.
◦ Check Out — Checks out (locks) the selected unlocked CMS object.
You have the option to check out any dependant objects in the same operation. This menu choice is only available for PTC Server connection objects.
◦ Undo Check Out — Cancels the check out of a CMS object and discards any changes made to that checked out version.
After canceling the check out of an object, if the document object is open in the Arbortext Editor, it will change to read-only. This menu choice is only available for PTC Server connection objects.
◦ Properties — Displays the Object Properties dialog box containing the properties of the selected object.
This menu choice is only available for PTC Server connection objects.
◦ Search CMS — Displays the Search dialog box.
This menu choice is only available for PTC Server connection objects. The Search dialog box allows you to enter a query to find all CMS objects matching some search criteria. Search results appear in the CMS Search Results node of the Resource Manager browser.
◦ Clear CMS Search Results — Clears any CMS objects that have been added to the CMS Search Results part of the Resource Manager browser.
This menu choice is only available for supported CMS adapters. This option does not remove those objects from the CMS, just from the Resource Manager browser.
◦ Synchronize Location Across Tabs — Determines whether the first location you browse to in the Resource Manager browser is maintained when you switch to a different tab or open another Resource Manager dialog box.
The setting of the ditasynctabs advanced preference determines whether this feature is on or off by default.
• Previous Folder button This is an image of a folder with a blue arrow superimposed pointing backwards. — Moves the location displayed in the browser to the last folder that was displayed in the browser.
The Resource Manager maintains a history of the folders you have viewed in the current session, so you can use this button to move the browser view back through that history. If you have viewed only one folder in the current session, this button is disabled.
• Up One Level button This is an image of a folder with a blue arrow superimposed pointing up. — Moves the location displayed in the browser up one level in the current hierarchy.
If you are at the top of the hierarchy, this button is disabled.
• Current Document Folder button This is an image of an open folder with a document sticking out and a blue arrow superimposed pointing to the side. — Moves the location displayed in the browser to the folder that contains the current document.
• Refresh button This is an image of a white document with two blue arrows superimposed pointing in a circle. — Updates the browser view to reflect any changes made to the objects displayed in the browser.
• Browse the Web button This is an image of a white document with a globe superimposed. — Changes the Key Definition tab to the state for inserting references from the Internet.
• Use CMS Object Browser button This is an image of a file cabinet. — Invokes the Browser for the PTC Server connection or a repository adapter.
This button is only available when you are connected to a content management system (CMS) through the PTC Server connection or a repository adapter.
• Search CMS button This is an image of a pair of binoculars over a file cabinet. — Invokes the Search dialog box.
This button is only available for PTC Server connection objects. The Search dialog box enables you to enter a query to find all CMS objects matching some search criteria. Search results appear in the CMS Search Results part of the Resource Manager browser.
• Filter — Enables you to filter the list of files and document elements displayed in the browser.
When you enter text in this option, the list of files and document elements displayed in the browser is filtered to just show the files or elements for which the labels contain the text you have entered. In this case, the Filter option and the browser display a light yellow background color to indicate that the contents of the browser are being filtered.
For example, if you enter “test”, then just objects with labels containing “Test”, “testing”, “test cases”, and so forth are displayed in the browser. If you have expanded a document to show the elements inside the document, then the displayed elements are also filtered. In this case, the document remains displayed in the browser even if its label does not contain the filter text.
Filtering is case insensitive. Folders and similar objects are not filtered. If you enter multiple terms in the Filter option, the matching labels must contain all of those terms.
• Resource Manager browser — Provides a file system, content management system (CMS), or document hierarchy.
The Resource Manager browser enables you to locate content in either a file system or a CMS to insert into your document. The browser provides a hierarchical view of the contents of the file system or CMS. In addition to showing folder and files, the browser also enables you to view the contents of DITA documents. For example, when you are using the Key Definition tab, the browser shows you the elements in a DITA document that are available for use as the target of a key definition based on the current context in the document. If a title for an element is available, the title is displayed in the browser next to the element. The element's ID (depending on the setting of the ditahideids advanced preference) and any href attribute value is also displayed.
If an element displayed in the browser already has a key reference value in the keyref attribute, that is indicated by a special icon This is an image of a key with a blue arrow.. Selecting an element in the browser automatically fills in some of the options in the Key Properties section of the dialog box. For example, if the selected element has a title element, the contents of that element are put in the Title option. Which options are filled in is determined by the selected element.
The browser contains a Favorite LocationsThis is an image of a yellow star. node that contains the list of the favorites locations you have saved. Double-clicking on one of the favorites opens that location in the browser. If a favorite location is not currently available, for example if the location has been deleted or is a CMS folder and you are not logged onto the CMS, then the folder has special icon This is an image of a folder with a red rectangle containing a white exclamation point on top. to indicate that status.
The browser also contains a HistoryThis is an image of a folder with a blue superimposed arrow pointing backwards. node that contains a list of all the locations you have visited in the current session. Double-clicking on one of the locations opens that location in the browser.
Click on the plus sign ( + ) in the hierarchy to open a level in the hierarchy or the contents of a document. Click on the minus sign ( – ) to close a level or document. Click on an object in the hierarchy to select it. Double-click on a folder to move the browser focus to that folder.
If you double-click on the The Web node in the browser, the tab changes to the state for inserting references to Internet documents.
• Type — Determines the type of document displayed in the Resource Manager browser.
Use this drop-down list to filter the documents displayed in the browser by the type of document. You can choose the following types of documents:
◦ Topic, Map, or Image — Display either DITA map and topic documents and graphic files.
◦ Topic — Only display DITA topic documents.
◦ Topic or Map — Display either DITA map or topic documents.
◦ Map — Only display DITA map documents.
◦ Image — Only display graphic files.
◦ PDF — Only display PDF documents.
◦ HTML — Only display HTML documents.
◦ Any — Display all types of documents.
• Show — Determines the type of elements displayed for DITA documents in the Resource Manager browser.
Use this drop-down list to filter the elements displayed for documents in the browser by the type of element. You can choose the following types of elements:
◦ All elements
◦ All elements with IDs
◦ Key Definitions
◦ Key References
• Key Properties — Enables you to specify the properties of a key definition.
Use the options in this section of the Resource Manager to set the properties of the key you are defining. The number of options available depends on the type of DITA map you are editing. If you are editing a DITA Key Definition Map, more options are available. These additional options provide more details about the key in the Insert Key Reference dialog box.
The following key properties are available:
◦ Clear button — Removes any content you have entered into the key property options.
When you enter content into one of the key property options, the label of that option turns blue. Once you have modified the contents of a property, it no longer updates if you change the selection in the browser. Clicking this button clears the content from any modified options, turns the labels back to black, and restores any default values.
◦ Name — Provides the name of the key.
You can enter one or more key names separated by spaces. If you select an element in the browser that already has a key reference defined, the value of the keyref attribute is inserted in this option by default. If you enter an invalid key name, the label of this option turns red and an error is displayed in the status bar. A message is also displayed in the status bar when the key name is a duplicate of another key definition in the same key context.
◦ Title — Provides a title for the key.
The value here is put in the navtitle attribute for the key definition in case of DITA 1.3 documents.
◦ Description — Provides a description of the key.
This option is only available when you are editing a DITA Key Definition Map. The value here is put in the keydescription element in the key definition.
◦ Element ID — Provides the ID for the element selected in the browser.
If the selected element already has an ID, the value of that ID is inserted in this option by default. If the selected element does not have an ID, you can generate one for it with the Generate ID button.
This option is only available when you are editing a DITA Key Definition Map. The value here is put in the value attribute for the keysubelementid element in the key definition.
◦ Generate IDThis is an image of the Generate ID toolbar button. button — Generates an ID for the element selected in the browser and updates the document containing the element.
This option is only available when you are editing a DITA Key Definition Map.
◦ Reference Tags — Provides the list of elements that reference the key.
You can enter one or more element names separated by spaces. Depending on the element you select in the browser, some element tags are inserted by default. Note that this field is not checked to see if the tag names are valid.
This option is only available when you are editing a DITA Key Definition Map. The value here is put in the value attribute for the keyreftags element in the key definition.
• Insert — Determines the type of element to insert into the map.
Use this drop-down list to select the type of element to insert into your document.
• Insert button — Inserts the key definition into the map you are editing.
If the current context in your document is not a valid insertion point, this button is disabled.
Options for Inserting Key Definitions to Documents on the Internet
For inserting key definitions to a document on the Internet, the Key Definition tab contains the following options:
• Look in — Determines the state of the Key Definition tab.
This option is always set to The Web when you are inserting a key definition to a document on the Internet. Selecting a different location from the drop-down list changes the state of the tab to that for inserting definitions to local documents.
Menu button This is an image of a document. — Displays a menu that contains the following options:
◦ Open (suffixed with Document) — This choice is disabled.
◦ Search CMS — Displays the Search dialog box.
This menu choice is only available for PTC Server connection objects.
◦ Clear CMS Search Results — Clears any CMS objects that have been added to the CMS Search Results part of the Resource Manager browser.
◦ Synchronize Location Across Tabs — Determines whether the first location you browse to in the Resource Manager browser is maintained when you switch to a different tab or open another Resource Manager dialog box.
The setting of the ditasynctabs advanced preference determines whether this feature is on or off by default.
• Previous Folder button This is an image of a folder with a blue arrow superimposed pointing backwards. — Moves the location displayed in the browser to the last folder that was displayed in the browser.
If the last location you viewed in the browser is not The Web, the state of the tab changes to that for inserting references to local documents.
• Up One Level button This is an image of a folder with a blue arrow superimposed pointing up. — This button is disabled.
• Current Document Folder button This is an image of an open folder with a document sticking out and a blue arrow superimposed pointing to the side. — Moves the location displayed in the browser to the folder that contains the current document.
The state of the tab changes to that for modifying references to local documents.
• Refresh button This is an image of a white document with two blue arrows superimposed pointing in a circle. — This button is disabled.
• Browse the Web button This is an image of a white document with a globe superimposed. — This button is disabled.
• Use CMS Object Browser button This is an image of a file cabinet. — Invokes the Browser for the PTC Server connection or a repository adapter.
This button is only available when you are connected to a content management system (CMS) through the PTC Server connection or a repository adapter.
• Search CMS button This is an image of a magnifier over a file cabinet. — Invokes the Search dialog box.
This button is only available for PTC Server connection objects. The Search dialog box enables you to enter a query to find all CMS objects matching some search criteria. Search results appear in the CMS Search Results part of the Resource Manager browser.
• URL — Displays the URL to be inserted for your key definition.
You can either edit this field to add the desired URL or select the Get Browser URL button to insert the URL for the web page displayed in your active web browser into the option.
• Open Browser — Opens your default web browser.
If there is a URL in the URL option, the web browser opens with that web page displayed. Note that you must have a default web browser set either in your operating system or in the Preferences dialog box’s File Locations preferences to use this option.
• Get Browser URL — Inserts the URL for the web page displayed in your active web browser into the URL option.
Note that you must have a default web browser set either in your operating system or in the Preferences dialog box’s File Locations preferences to use this option.
• Key Properties — Enables you to specify the properties of a key definition.
Use the options in this section of the Resource Manager to set the properties of the key you are defining. The number of options available depends on the type of DITA map you are editing. If you are editing a DITA Key Definition Map, more options are available. These additional options provide more details about the key in the Insert Key Reference dialog box.
The following key properties are available:
◦ Clear button — Removes any content you have entered into the key property options.
When you enter content into one of the key property options, the label of that option turns blue. Once you have modified the contents of a property, it no longer updates if you change the selection in the browser. Clicking this button clears the content from any modified options, turns the labels back to black, and restores any default values.
◦ Name — Provides the name of the key.
You can enter one or more key names separated by spaces. If you enter an invalid key name, the label of this option turns red and an error is displayed in the status bar. A message is also displayed in the status bar when the key name is a duplicate of another key definition in the same key context.
◦ Title — Provides a title for the key.
The value here is put in the navtitle attribute for the key definition.
◦ Description — Provides a description of the key.
This option is only available when you are editing a DITA Key Definition Map. The value here is put in the keydescription element in the key definition.
◦ Element ID — This option is disabled.
◦ Generate IDThis is an image of the Generate ID toolbar button. button — This option is disabled.
◦ Reference Tags — Provides the list of elements that reference the key.
You can enter one or more element names separated by spaces. Some element tags are inserted by default. Note that this field is not checked to see if the tag names are valid.
This option is only available when you are editing a DITA Key Definition Map. The value here is put in the value attribute for the keyreftags element in the key definition.
• Insert — Determines the type of element to insert into the map.
Use this drop-down list to select the type of element to insert into your document.
• Insert button — Inserts a key definition to the designated URL into the map you are editing.
If the current context in your document is not a valid insertion point, this button is disabled.