Generating and using IDs for DITA elements

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.

The Oxygen SDK (Part 1: Plugins)

During the last years we added a lot of API and extension points to Oxygen in order to allow for different customizations to the application.

But our documentation is sometimes lacking. We mostly rely on Javadoc documentation and on Java samples.

Here's some feedback we got at the last Oxygen Users Meetup in Munich this year:

Too less information about frameworks, plugins, everything is spread over certain documents, webinars, etc . Please centralize these information in one form.

I will try to centralize these resources and add some useful links for people who want to start customizing Oxygen.

First the difference between a framework and a plugin:

• A plugin can be used to customize the behavior of the entire application no matter what XML document is currently being edited.

• A framework configuration provides validation, content completion and editing support for a specific XML vocabulary.

 

Plugins:

A plugin is a folder containing a descriptor plugin.xml file and various other JAR libraries and resources.

http://www.oxygenxml.com/doc/ug-oxygen/index.html#topics/preferences-plugins.html

Only the standalone version of Oxygen supports plugins.
The Eclipse Plugin version of Oxygen is itself a plugin and can be customized by adding a plugin in the Eclipse workbench which depends on the Oxygen Eclipse plugin.
Despite of this, most of the API is common.

The plugin can be deployed either by copying it to the plugins folder of an Oxygen installation:

http://www.oxygenxml.com/doc/ug-oxygen/tasks/howto-install-plugin.html

 or by deploying it as an add-on:

http://www.oxygenxml.com/doc/ug-oxygen/index.html#tasks/deploying-addons.html

The Oxygen Plugins SDK:

http://www.oxygenxml.com/oxygen_sdk.html#Developer_Plugins

contains Java sources and Javadoc for all the API accessible from a plugin.

The Plugins SDK also contains sample plugins and their Java code. This Java code should be very helpful to get you started and to show how various API can be used.

Although there are many types of plugins:

http://www.oxygenxml.com/doc/ug-oxygen/index.html#topics/pluginTypes.html

the most useful plugin extension type is the "Workspace Access" extension type:

http://www.oxygenxml.com/doc/ug-oxygen/index.html#concepts/workspace-access-plugin.html

This kind of plugin allows you to use the API and add or remove toolbar and main menu buttons, add custom views and toolbars. It also allows you to access and control/make changes to the XML documents opened in the workbench.

As an example, all full-featured integrations which have been created to connect Oxygen with a specific CMS or remote repository use a combination of "Workspace Access" and "Custom Protocol" plugin:

http://www.oxygenxml.com/doc/ug-oxygen/index.html#topics/howto-cms-plugin.html

You can create automated tests for your plugins:

http://www.oxygenxml.com/doc/ug-oxygen/index.html#topics/automated-tests.html

and even debug their functionality:

http://www.oxygenxml.com/doc/ug-oxygen/index.html?q=/doc/ug-oxygen/topics/debug-plugin.html