Edit online

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 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:

Converting Conrefs to Conkeyrefs

Oxygen XML 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 ToolsXML ToolsXML menu (or from the Refactoring submenu when you right-click a document in the ProjectProject 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.
- Look inside archives - If this option is selected, the scope of the operation will include files inside archives.

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.