VideosWorking with DITA Reusable Components View in Oxygen XML Editor 19.1


Duration: 09:46
This demonstration shows you how to use the DITA Reusable Components view in Oxygen XML Editor. This view is helpful for DITA documentation projects that utilize a large amount of keys and reusable components.


00:00:07In this demonstration, I will show you how to use the DITA Reusable Components view in oXygen XML Editor.
00:00:14This view is helpful for DITA documentation projects that utilize a large amount of keys
00:00:20and reusable components.
00:00:22This view is hidden by default, so if it is not displayed, it can be opened by selecting
00:00:29it from the Window -> Show View menu.
00:00:33The view includes two tabs and it collects all the keys and reusable components that
00:00:39are defined in the root map structure and presents them in a dynamic table where you
00:00:45can easily locate and insert references to them.
00:00:54First I'll show you how to use the Keys tab...
00:00:58Notice that it has a tabular structure with columns that display the key names, their
00:01:04description, the href where the keys point to, and the location of the map file where
00:01:10the key is defined.
00:01:12This Keys tab displays all of your keys and provides ways to easily insert references
00:01:19to them as cross reference links, key references, or variables.
00:01:26Another nice feature that helps you to see where the keys are defined is the ability
00:01:31to group them by definition location.
00:01:34To demonstrate how to use this tab, I am using the oXygen user's manual project, which contains
00:01:40hundreds of key definitions.
00:01:43I have a topic opened where I've identified some content that needs to be replaced with
00:01:48keys and I'm going to show you several different ways to insert them using this view.
00:01:56First off, I've noticed that the name of our product appears at the beginning of the first paragraph.
00:02:02I know I have a key defined for it so I'll use the Search filter to look for this particular key.
00:02:10Notice that the contextual menu includes a "Go to Definition" action that allows you
00:02:14to open the file where the key is defined and see that particular key definition.
00:02:21Now I'm going to replace the product name that is in plain text in my topic with the
00:02:25appropriate key using the Reusable Components view.
00:02:30One way to do this is to simply drag the key and drop it into my document.
00:02:35Note that if the selected key has an "href" value, it is inserted as a cross reference
00:02:43If it's a reference to an image, it's inserted as an "image" element.
00:02:47Otherwise, it is inserted as a variable reference inside a "ph" element.
00:02:54I'll briefly switch to The Full Tags mode just to show you that Oxygen inserted this particular
00:03:00key as a variable in a "ph" element since our product key does not have an "href" value.
00:03:08Next, I've noticed that I have the word "perspectives" wrapped in a 'term' element.
00:03:15I know that I have a glossary term for this word defined as a key and in the output I
00:03:21want that term to be a link to that key reference.
00:03:25So, I'll select that whole 'term' element and now I just need to find that specific
00:03:31key in the Reusable Components view.
00:03:34In our documentation project, all keys that were created for glossary terms have the same
00:03:39naming convention.
00:03:41They begin with "glossentry", so I can simply search for 'gloss'...
00:03:48As you can see that all of our glossary terms are listed and sorted alphabetically.
00:03:54By the way, you can change the sorting of any of the columns in this tab simply by clicking
00:04:00on the column header.
00:04:02Now I'll show another method for inserting the key references, so I'll scroll down and
00:04:07locate my "perspective" glossary term... ... and I can simply double-click the key.
00:04:13In this case, since this particular key has an "href" value, notice that oXygen inserted
00:04:20it as a cross reference link inside an "xref" element.
00:04:26There's one more method you can use to insert key references ... by using actions found
00:04:32in the contextual menu.
00:04:34I have another instance of the word "perspective" and this time it's not already inside a "term"
00:04:40element and I want to insert a reference to that same "perspectives" glossary entry.
00:04:46So, in this instance, I'll delete that word.
00:04:49...this time I'm going to right-click that key in the Reusable Components view...
00:04:55...and notice that there are several options that I can choose from...
00:04:59...for my purposes, I'll select "Insert as Keyref"...
00:05:03...notice that this option presents a submenu that lists all the elements that can be inserted
00:05:09at the current cursor position.
00:05:12I want it inserted inside a "term" element so I'll scroll to "more" and select that element.
00:05:22Notice that this time Oxygen inserted the key reference inside the "term" element.
00:05:35Now I want to show you the Components tab.
00:05:38This tab displays all the topics (from the root map) that contain reusable components
00:05:44and it provides ways to easily insert them as content references or content key references.
00:05:51To determine which topics will be displayed in this tab, the DITA Reusable Components
00:05:57view considers topic references that contain a processing-role attribute set to "resource-only"
00:06:04to be candidates to contain reusable components.
00:06:07Futhermore, the reusable components inside these topics are collected from all elements
00:06:13that have an ID specified.
00:06:16These reusable components are displayed in the Components tab along with:
00:06:21- the ID of the container and the ID of the component
00:06:24- the specific name of the element that contains the reusable content
00:06:29- a short preview of the content - the name of the file where the component is stored
00:06:36This tab includes a search field that allows you to filter the text content...
00:06:41some filtering options ... for example, I can choose to only show a certain type of element...
00:06:51... or I can narrow down the list of files
00:06:54by using the Target file field.
00:06:58To demonstrate how the search mechanism works, suppose that I have this section in our User Guide,
00:07:03where it describes how you can move editor tabs.
00:07:07I already have one method documented, but I need to add two more shortcut methods.
00:07:13I know that we have a reusable container topic where we've defined all of our shortcuts keys,
00:07:20and I don't remember the specific name of the file, but I know that it has the word
00:07:25"shortcuts" in its name.
00:07:27So, in the "Target file" field and I'll enter "shortcuts".
00:07:33Notice that the list is now filtered to display only the files that have "shortcuts" in their name.
00:07:39Now I know that the two shortcuts contain the Comma and Period keys, and also that one
00:07:45of the modifier keys is Alt, but I can't remember the second modifier key.
00:07:52Since the search field allows you to use search patterns, I'll use one to help narrow
00:07:56down the targets.
00:07:59This did not narrow it down enough since the string "comma" also matches "Command".
00:08:06So I'll refine my search pattern even more by using double quotes for the Comma string...
00:08:13... and I can refine it even more since I know that "Alt" is one of the modifier keys.
00:08:20This narrowed the targets down to exactly what I'm looking for...
00:08:24So now I'll show you several ways to insert the components in a topic as conrefs or conkeyrefs.
00:08:32In my case, I need to insert a new definition list item...
00:08:37.. and I'll insert the first shortcut just by clicking the Insert link that appears when
00:08:42you hover over the component.
00:08:45Note that if the parent topic of the selected component has a key defined, by default it
00:08:50is inserted as a conkeyref.
00:08:53Otherwise, it is added as a conref.
00:08:57Now I'll insert its description by double-clicking the component.
00:09:03Then I need another "dlentry" ... and this time I'll use the contextual menu action to insert the component
00:09:12... and notice that I can choose whether to insert the component as a conref
00:09:17or as a conkeyref.
00:09:20Another way to insert a component is to drag the component from the view and drop it at
00:09:25the proper location in the document.
00:09:29So, those are the basics for how you can use both tabs in the DITA Reusable Components
00:09:34view to easily insert references to reusable content.
00:09:39And this concludes the demonstration.
00:09:41Thanks for watching!

Use Oxygen Feedback to ask us anything about this video.