Editing DITA Content References

When you reference reusable content using a @conref or @conkeyref attribute, by default, the content is grayed out in the document and can only be edited from the source document. To edit the source of the referenced content, click the icon at the beginning of the inserted content. This will open the source document where you can edit the referenced content.

Oxygen XML Author Eclipse plugin also includes some actions that allow you to quickly edit existing content references. When the element that contains a content reference (@conref or @conkeyref) is selected, the following actions are available in the DITA menu and the Reuse submenu of the contextual menu:

Edit Content Reference

This action is available for elements with a @conref or @conkeyref attribute. It opens the Edit Content Reference dialog box that allows you to edit the source location (or key) and source element of a content reference (or content key reference), and the reference details (@conref/@conkeyref and @conrefend attributes). For more information, see Reuse Content Dialog Box.

Replace Reference with Content

Replaces the referenced fragment (@conref or @conkeyref) at the cursor position with its content from it source. This action is useful if you want to make changes to the content in the currently edited document without changing the referenced fragment in its source location. If the source content includes references to other topics/resources (hrefs), the operation also resolves those references relative to the new location. Attributes are preserved according to the following priority:

Attributes from the elements in the current document that reference other content are preserved except for attributes with a -dita-use-conref-target value.
Attributes from the referenced content are brought into the replaced elements in the current document except for @id attributes.

Replace All References with Content

Replaces all referenced fragments (@keyref, @conref, or @conkeyref) in the current document with the content. Attributes are preserved according to the following priority:

Attributes from the elements in the current document that reference other content are preserved except for attributes with a -dita-use-conref-target value.
Attributes from the referenced content are brought into the replaced elements in the current document except for @id attributes.

For keyrefs inside <xref> or <link> elements, the @keyref attribute is changed to an @href attribute, while the rest of the content for the keyref is replaced with its source content.

If the source content includes references to other topics/resources (hrefs), the operation also resolves those references relative to the new location.

Remove Content Reference

Removes the content reference (@conref or @conkeyref) inside the element at the cursor position.

Converting Conrefs to Conkeyrefs

Oxygen XML Author Eclipse plugin includes a DITA refactoring operation called Convert conrefs to conkeyrefs that will find all content references (that reference content outside the current document) and convert them to content key references. You can also use it to quickly convert all content references in the current document or multiple documents at once.

To access the Convert conrefs to conkeyrefs operation, use one of the following methods:

Single Document Method: With the document opened in the editor, right-click anywhere in the main editing pane (or right-click the topic reference in the DITA Maps Manager), go to the Refactoring submenu, and choose Convert conrefs to conkeyrefs.
Multiple Documents At Once Method: Select XML Refactoring from the XML menu (or from the Refactoring submenu when you right-click a document in the Project Explorer viewor the DITA Maps Manager view). Then select Convert conrefs to conkeyrefs from the DITA section and click Next.

Either method will proceed to the XML Refactoring Wizard. If you used the Multiple Documents At Once Method, the wizard page allows you to choose a scope for the operation and some filtering options:

Scope - Select from a variety of options to define the scope that will have resources affected by the operation. For example, you can choose to affect all resources in the Project, All opened files, Current DITA map hierarchy, or just the Current file.
Filters section
- Include files - Specifies files to be excluded from the operation. You can specify multiple files by separating them with commas and the patterns can include wildcards (such as * or ?).
- Restrict to known XML file types only - Excludes non-XML file types from the operation.

If you used the Single Document Method, the scope will be the current file so the scope and filtering options are not displayed.

You can then use one of the following buttons to proceed with the operation:

Preview: You can use the Preview button to open a comparison panel where you can review all the changes that will be made by the refactoring operation before applying the changes.
Warning: It is always recommended to use the Preview button to make sure the operation is not going to do something unexpected and after you click the Finish button, any Undo action will only revert changes on the current document.
Finish: When you use the Finish button, the operation will be processed and all content references will be converted to content key references (either all content references in the current document or all content references in all of the documents specified in the scope). The file name for each converted document is used as the value for its new key. However, the operation does NOT automatically add the key to the DITA Map, so you still need to manually define each key in your DITA map.