Generating and using IDs for DITA elements
Generating IDs in DITA
ID values can be generated either
on request or
automatically for DITA elements.
 |
| Generate ID values on two paragraphs using the contextual menu |
The action that you can invoke to generate IDs is called
Generate IDs
and you can access this from the
contextual menu or from the
DITA main
menu. The action acts on the current selection or, if there is no
selection, on the current element. The format of the ID value as well as the elements on which ID values are generated automatically can be customized from the
DITA->ID Options menu.
 |
| DITA -> ID Options menu |
The default settings will configure oXygen to generate automatically IDs for topics, tables, figures and lists and the ID value will start with the element local name followed by some unique string.
The elements for which ID values will be generated automatically are specified using class attribute values, that means the automatic ID generation is
specialization-aware, it will work not only for the elements defined as part of the DITA standard, but also for any custom specialization that defines its own specialized topics, tables, figures or lists.
 |
| The ID Options dialog |
The pattern for the ID values can be customized using constant strings and editor variables. The common editor variables that are used for these values are
${lcoalName},
${id} and
${uuid}, please refer to
the user guide for more information on editor variables.
The ID value of an element can be manually added, removed or modified using the
Attributes panel to access the
id attribute of that element.
This action to generate ID values for DITA is part of the
DITA framework configuration, so you can easily remove it or configure a different custom action to generate IDs. But in general, you should not need to change the ID generation because specific ID values should not matter that much.
Using IDs in DITA
Elements that have an ID value defined for their
id attribute can be referred by that ID value from other parts of the DITA topic or from other topics, in order to create
links or to
reuse those elements. oXygen provides DITA specific actions to create DITA links and content references as part of the DITA framework. These default actions feature
search and
filter capabilities that should help you identify the element to point to, without the need to put semantic information in the ID value itself.
Here it is an example of adding a content reference to a topic. Let's say we have this topic talking about inserting the SIM card in a phone. For that we need to remove the battery, insert the SIM and then add the battery. If we already have a task for removing the battery then we can reuse those steps instead of duplicating them. At the beginning of the steps element we need to add a content reference to refer to the steps from the task that describes how to remove the battery.
 |
| A task that describes how to insert a SIM in a telephone |
We position the caret inside the
steps element, before the first
step and invoke the
Insert a DITA content reference action. This will show the
Insert Content Reference dialog.
 |
| The insert content reference dialog |
Now, let's suppose we do not remember the task file name that talked about removing the battery, what can we do? We can use the drop-down from the action next to the
URL field and choose
Search for file.
 |
| Trigger the Find Resource dialog |
Now oXygen will show the
Find Resource dialog where you can search for content to identify the task that describes how to remove the battery. For example, once you start typing in the search field "
rem", oXygen will show you the topics that match this prefix, sorted by relevance.
 |
| The Find Resource dialog showing topics that match the search criteria |
The first match seems to be the one we want, if we look at the title, so we select it. oXygen will load that topic in the
Insert Content Reference dialog and it will present all the defined IDs, showing a preview of each entry you select.
 |
| Insert content reference displaying the available IDs in a topic |
Now, you can
filter on the
type of element that you want to refer using the Target Type combobox and you can also filter on
content,
topic ID and
element ID using the Filter input. As the content is dynamically gathered from each element,
it is a better practice to use this search functionality than to put part of the content in the ID value. If the content changes in time that ID value will be very difficult to maintain to keep it up-to-date with the changes made to content - either you leave an old ID value that does not match the updated content, or you change the ID value and then you need to change all the references to that ID.
We can
filter for example to see only the
task steps that
contain "remove"
 |
| Filtered IDs |
We see now the entry that we want, we preview it and choose to make a conref to this step.
 |
| The topic contains a content reference to the identified step |
This functionality
works similarly for links and helps you search on the content itself and not on the ID value to refer to an element.
The search functionality is available also directly in oXygen, both as a dialog and as a side view, for example if you use
Window->Show View->Open/Find Resource then you will see the
Open/Find Resource view that will help you
search through all your resources,
in content,
in file paths and
in reviews. The content search also supports XML elements, for example "
title:battery" will
find all topics that have the word battery in their title.
 |
| The find resources view |
You can then open the topic you found, maybe generate IDs for elements that you want to reuse and then you can also
drag and drop or
copy and
paste as link or
paste as content reference to quickly link or reuse that content.
Some conclusions
You can use oXygen to automatically add ID values the elements that you usually reuse in your DITA topics or you can generate ID values on request, for specific elements. You can customize to some degree the ID format but that should not be very important, because if you want to store semantic information inside the ID value, like adding some of the content of the element, then maintenance will became a nightmare. Instead, you should take advantage of the search and filtering support that oXygen provides to search for the actual content of the element you want to link to.
