DITA content references

Know what are content reference in a structured document and how they can be used to create a reference to content from another DITA topic.

A content reference (conref) is used to create a reference to content (elements) from a DITA topic or DITA map in another DITA topic. Using a conref you can reuse content (elements) across DITA topics. A conref is based on the DITA ID attribute assigned to the element. This implies that if the position of an element in the topic changes, the reference remains intact as long as the ID remains intact.

You can use direct referencing to point directly to the DITA topic (.xml file) containing the target topics or elements. Alternatively, you can use indirect referencing to point to keys defined in keyspaces. For more details, see DITA referencing.

You can create conrefs for almost any element in the DITA element catalog. You create conrefs for a DITA topic to make an entire topic reusable. You can also create a conref for a <keyword> or <ph> element to reuse a <term> or even word. The only requirement to create a conref is that the element must define the DITA ID attribute.

Set up a topic to use conrefs

Learn to set up a topic to use conref in FrameMaker.

To create a conref in your DITA topics, you first need to create a DITA topic (direct referencing) or a DITA map (indirect referencing) that contains the content (elements) that you plan to reuse. For example, say you plan to reuse a table, an ordered list, and an image across multiple topics. You will need to add these elements to the source topic. If you are using indirect referencing, the topic is then added to the DITA map. Also, to make an element reusable, you need to assign a unique identifier to the element. For details, on how to make DITA content reusable, see Set up reference content.

DITA Conref dialog

Learn to set up a topic tLearn to use DITA conref dialog to add direct and indirect conrefs to DITA content in FrameMakero use conref in FrameMaker.

Use the DITA Conref dialog to add direct and indirect conrefs to DITA content.

To open the DITA conref dialog:

Choose Insert > Conref.

DITA conref dialog

Use the DITA Conref dialog to:

A (Target > File):

Select this option to insert a conref using DITA referencing. See Create a conref.

B (Target > Key):

Select this option to insert a conref using DITA referencing. See Create a DITA link.

C (Target > Both):

Check this option to create a link using direct or indirect referencing.

D (File/Key Settings):

If the target is set to File, select a DITA topic from the list of currently opened topics for direct references. You can also browse to select a topic that is not currently opened.

If the target is set to Key, select a key for indirect reference. You can also open the DITA Keyspace Manager dialog. In this dialog, you Create a keyspace and set the default keyspace for the current topic.

E (Filter Text):

Search for the required topic or key that you want to create a link to. This smart search filters the elements as you start typing in the Filter Text box. You can filter content on the basis of the element tag, ID, or text (content).

Once you have found the required topic, select an element to include as a link. The link element defines a relationship to another topic.

F (Conref End Element):

Select an element as the last element in the range of elements to conref. For details, see Creating a conref to a range of elements.

Working with conrefs

See how you can work with conrefs, create and update conrefs in FrameMaker.

You can create a conref in a DITA topic or map using the DITA Conref dialog.

This section covers the following topics:

Create a conref
Creating a conref to a range of elements
Updating conrefs

Create a conref

To create a conref to a DITA topic or map in your current topic or map, you first need to Set up reference content in the target topics or maps

Next, you create a direct or indirect reference to the target DITA content.

Place the insertion point at the location to insert the conref in a topic or map.

To insert a conref at a location in the topic, you need to place the insertion point relevant to the conref element:

An <li> (list item) conref element must be placed in an <ol> or <ul> list.

A table <row> must be placed in a <table> or <simpletable>.

In the case of a table <entry>, you cannot place the insertion point in the table <row>; you need to select the existing <entry> that you want to replace.
Choose Insert > Conref.

The DITA Conref dialog is displayed.
You can choose to add a link as a direct or indirect reference to the target content. For details, see DITA referencing.

To create a direct reference to the target content:
1. Select the File option for the Target and choose the file containing the reference topic.
2. You can select a reference topic from the current topic, any currently opened topic, or use the browse button to select an unopened topic.
3. After you select the DITA topic, the element list displays the elements to which unique identifiers are assigned.
  
  The elements in the DITA topic of the selected element tag that are assigned a unique identifier are displayed in the elements list. If an element is not assigned a unique ID, you can Assign a unique ID to an element.
4. Select an element to insert as a conref in the current topic.
  
  The list also displays the ID and the contents (in the case of text elements) of the elements.
If you make changes to a <conref> element in the source topic, you will need to save the source topic and update the container topic to view the updates.

To create an indirect reference to the target content:
1. Select the Key option for the Target and click Keyspace Manager.
2. In the DITA Keyspace Manager dialog, select the key in the defined keys list and click OK.
  
  For details on how to add key references, see Using keyspaces to manage DITA key references.
  
  After you select the key, the element tags list displays the DITA topic types included in the keyspace. You can read more on how to Create a keyspace.
3. Select an element tag.
  
  The elements in the DITA topic of the selected element tag that are assigned a unique identifier are displayed in the elements list. If an element is not assigned a unique ID, you can Assign a unique ID to an element.
4. Select an element to insert as a conref and click OK.
Click Insert.

Creating a conref to a range of elements

You can create a conref to a range of elements. For example, say you have number of <p> (paragraphs) elements that you want to conref in a range. You can create one conref to all the <p> elements.

Note: To specify a range for the content reference, the elements within the range must be of the same type. At least the start and end elements must have unique identifiers.

To select the first element in the range perform steps in the section Create a conref but do not click <Insert>.
In the Conref End Element drop-down list, choose the last element in the range to include in the conref.
Click Insert.

Updating conrefs

If you update a reusable element after you reference it in another topic, you need to update the conrefs in the topic to view the updates.

To update the conrefs in a topic:

Choose Structure > DITA > Update References.

The DITA Update References dialog is displayed.
Check Update All Conrefs in File.
Click OK.

All the conrefs in the current topic are updated.