Generating IDs for Elements in Author Mode

Generate IDs On-Request

You can generate ID values for specific elements on-request. To do so, select the element that will have an ID generated (or place the cursor inside the element) and select the Generate IDs action from the contextual menu. This action generates a unique ID for the current element. If you invoke the action on a block of selected content, the action will generate IDs for all top-level elements and elements that are listed in the ID Options dialog box. To open this dialog box, open an XML document that belongs to that specific document type and then select ID Options from the DITA, DocBook, or TEI main menu (depending on your document type).

Note: The Generate IDs action does not overwrite existing ID values. It only affects elements that do not already have an @id attribute.

Automatically Generate IDs

Oxygen XML Author Eclipse plugin includes an option to automatically add unique ID values to certain elements when they are created in Author mode. The Auto generate IDs for elements option can be found in the ID Options dialog box that is displayed when you select the ID Options action from the framework-specific menu (DITA, DocBook, or TEI). If this Auto generate IDs for elements option is selected, Oxygen XML Author Eclipse plugin automatically generates unique ID values for elements that are listed in this dialog box. You can use this dialog box to customize the format of the ID values and choose which elements will have their ID values automatically generated (for example, you can customize the list of elements to include those that you most often need to identify).

ID Options Dialog Box

To configure options for generating IDs, select ID Options from the DITA, DocBook, or TEI menu (depending on your document type).

Figure 1. ID Options Dialog Box

The ID Options dialog box allows you to configure the following options with regard to generating ID values:

ID Pattern: The pattern for the ID values that will be generated. This text field can be customized using constant strings or any of the Oxygen XML Author Eclipse plugin Editor Variables.
Element name or class value to generate ID for: The elements that will have ID values generated, specified using class attribute values. To customize the list, use the Add, Edit, or Remove buttons.
Auto generate IDs for elements: If selected, Oxygen XML Author Eclipse plugin will automatically generate unique IDs for the elements listed in this dialog box when they are created in Author mode.
Remove IDs when copying content in the same document (DITA or TEI): When copying and pasting content in the same DITA or TEI document, this option allows you to control whether or not pasted elements that are listed in this dialog box should retain their existing IDs. To retain the element IDs, deselect this option.
Note: This option does not have an effect on content that is cut and pasted.
Remove IDs when copying content (DocBook): This option allows you to control whether or not pasted elements that are listed in this dialog box should retain their existing IDs in DocBook documents. If this option is not selected, IDs are always retained when you copy or cut content and paste it in the same document or other documents. If this option is selected, IDs are never retained for copied content, but if you cut the content, they are preserved for the first paste action (and not retained for any subsequent paste actions).

Duplicating Elements with Existing IDs

If you duplicate elements with existing IDs (for example, through copy/paste or drag/drop actions), all IDs are removed at the resolution of the operation. However, you can use the options in the ID Options dialog box to change this behavior. The options in this dialog box affect duplicated elements with existing IDs in the following ways:

Only the elements listed in this dialog box are affected by these options. Therefore, if you want to use these options to preserve IDs or generate new ones, you must first add the elements to be duplicated to the list in this dialog box.
If the Auto generate IDs for elements option is selected and you duplicate elements with existing IDs, Oxygen XML Author Eclipse plugin assigns new, unique ID values to the duplicates.
If the Auto generate IDs for elements option is not selected and you duplicate elements with existing IDs, the ID values are removed from the duplicates.
For DITA and TEI, if the Remove IDs when copying content in the same document option is selected, the ID values are removed from elements that are duplicated in the same document. If it is not selected, the ID values are preserved when elements are duplicated in the same document. Selecting this option has no effect if the Auto generate IDs for elements option is selected and this option has no effect on elements that are duplicated in other documents.
For DocBook, if the Remove IDs when copying content option is selected, the ID values are removed from any element that is duplicated. If it is not selected, the ID values are preserved when elements are duplicated. Selecting this option has no effect if the Auto generate IDs for elements option is selected.

Controlling the Default ID Generation Options

It is possible to configure the default ID generation options for DITA, DocBook, and TEI document types. In the frameworks folder for each of those document types, there is an XML configuration file called idGenerationDefaultOptions.xml that contains the default settings for generating IDs in each particular type of document. To configure the default settings, you can edit this file and save it back to the same directory.

The configuration file can be found in the resources folder within the particular framework. For example, the configuration file for the DITA framework is located in: [OXYGEN_INSTALL_DIR]/frameworks/dita/resources/idGenerationDefaultOptions.xml.

If you want to share your configured default ID generation settings with other members of your team, follow these steps:

Configure the idGenerationDefaultOptions.xml file for your framework according to your needs.
Bundle a modified version of the entire framework folder (for example, [OXYGEN_INSTALL_DIR]/frameworks/dita/). To do this:
1. Open the Preferences dialog box and go to Document Type Association.
2. Select your document type and click the Extend button.
3. In the Document type configuration dialog box that is now displayed, select External for the Storage option. By default, this will save the extension in a new folder in the frameworks folder (for example, [OXYGEN_INSTALL_DIR]/frameworks/dita-extension (1)), but you can also use the Browse button to specify a specific name and folder.
4. In this new extension folder, create a new folder called resources and add your modified idGenerationDefaultOptions.xml file to this new resources folder.
5. Go back to the Document Type Association preferences page, select the extended framework, and click Edit.
6. Go to the Classpath tab, add a reference to your new resources folder, and move this reference up (using the Move Up button) so that it is the first one that appears in the list.
7. Click OK and exit out of the preferences page.
Distribute your newly extended folder to other team members by using one of the methods described in Sharing a Framework.