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:40link.
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!