Element Reuse

You can reuse topic elements including steps, paragraphs, notes, figures, lists, sections, and more.

Overview

You reuse topic elements by using content references (conref attributes).

Figure 1. Element Reuse Operation.
The following example shows that:
  • “Element B” is reused in “Topic A” and “Topic B”
  • “Element C” is reused in “Topic B” and “Topic C”
Tip: You can view detailed reuse information about every file in easyDITA by right-clicking a file and selecting Links . The Links tab shows incoming links, outgoing links, or all file dependencies.

Example

The following examples show the element reuse mechanism in easyDITA. The topic editor indicates reused elements with a gray background in the target topic.

Figure 2. Element Warehouse Topic.

The following example shows a warehouse topic that includes two reusable topic elements (“Element B” and “Element C”). Each of these elements has an unique @ID attribute assigned. The unique @ID attributes enable you to reuse these elements.

Tip: easyDITA includes a reuse indicator that enables you to quickly check and navigate to the resource where an element is reused.
Figure 3. Topic A.

In the following example, “Element B” is reused from a “Warehouse Topic”.

Figure 4. Topic B.

In the following example, “Element B” and “Element C” are reused from a “Warehouse Topic”.

Figure 5. Topic C.

In the following example, “Element C” is reused from the “Warehouse Topic”.

Localization Considerations

If you localize content or plan to localize content, keep the following considerations in mind while reusing elements:

  • You can reuse the following types of elements:
    • Block elements (for example, section elements, paragraph elements, or note elements)
    • Inline elements (for example window title elements, UI control elements, or phrase elements)
  • Reusing inline elements may make your content difficult to localize because sentence structure can vary from language to language. Reused inline elements created in one language may cause grammatical errors in other languages.
  • Reusing block elements is safer than reusing inline elements. However, you should still pay attention to the context in which you reuse block elements.

Add Reusable Elements to Warehouse Topics

Create a warehouse topic that contains reusable elements.

Tip: We recommend grouping similar reusable elements in dedicated warehouse topics. For example, you can keep your note elements and step elements in separate warehouse topics. This strategy prevents your warehouse topics from becoming cluttered and disorganized as you add new reusable elements over time.
  1. In the content library, navigate to the folder where you want to create the warehouse topic.
    Tip: We recommend creating warehouse topics in a dedicated folder (e.g. _warehouse). Keeping warehouse topics in one place, makes it easy to find and update reusable content.
  2. Create a warehouse topic by doing the following:
    1. If you want to create a warehouse topic for general elements (e.g. note elements), click Create New > Default Topic template .
    2. If you want to create a warehouse topic for task elements (e.g. step elements), click Create New > Default Task template .
    3. In the Title field, enter a meaningful name for your warehouse topic.
      Enter notes_warehouse
    4. Click Create & Edit .
  3. Create the element that you want to reuse in other topics.
    Insert a note element and enter Read all instructions before you begin using this product.
  4. Assign a unique ID to the element by doing the following:
    1. Click the element that you inserted in 3.
    2. On the right, click the Attributes tab.
    3. In the Attributes tab, in the id field, enter a unique, meaningful identifier for the element.
      Enter noteReadAll
Reuse elements from your warehouse topic in other topics. See Reuse Elements from Warehouse Topics.

Reuse Elements from Warehouse Topics

You can reuse content by copy and pasting tags or by using the context menu.

Create a warehouse topic and add reusable elements. See Add Reusable Elements to Warehouse Topics.
Reuse elements by copying and pasting tags
  1. In the topic editor, ensure that you have the Short Tags, Full Tags, or Full Tags With Attributes mode enabled.
    For more information, see Tags.
  2. Open the source and target topics:
    1. Open the target topic in which you want to reuse content.
    2. Open the warehouse topic with the source content that you want to reuse.
    Tip: You can open the source and target topics side-by-side in two separate web browser windows.
  3. In the warehouse topic, right-click the tag of a reusable element and select Copy.
  4. In the target topic, reuse the content from 3:
    1. Right-click the place where you want to insert the content reference and select Paste.
    2. From the dialog, select Conref.
    Tip: Instead of copying and pasting elements in 3 and 4, you can drag and drop reusable elements from the warehouse topic to the target topic.
Reuse elements by using the context menu
  1. Open a topic and place your cursor where you want to insert a content reference.
  2. In the toolbar, click the Reuse icon.
  3. Select a warehouse topic by doing the following:
    1. Click the Select file button.
    2. In the Library dialog, select the warehouse topic.
  4. Select the element inside the warehouse topic that you want to reuse by doing the following:
    1. Click the Link Inside File (Select Target Element) button.
    2. In the Create/Edit Link dialog, select the element.
    3. From the list that appears, select the element.
    4. If prompted about the element ID, click OK and Save .
      Tip: easyDITA generates ID values automatically but you can enter your own values. The ID values must be unique. Assigning customized values may boost consistency in your documentation.
    5. Click the Insert Content button.

Edit Reused Elements

You can edit your warehouse topics without leaving the topic editor. It's possible thanks to the Edit Content option that opens your warehouse topic on top of the topic editor.

After you are done editing your reusable content, you close the warehouse topic and are back in topic editor where you left off.
CAUTION: Editing the reused element source impacts every topic that reuses this element.
  1. Open a topic that contains an element reused from a warehouse topic.
  2. Click the reused element.
    The Content reference toolbar appears.
  3. In the Content reference toolbar, click Edit Content .
    The element that you want to edit highlights.
  4. Edit the element.
  5. Click Done .
You edited a reusable element without leaving the topic editor. The change is applied to every topic that reuses this element.

Change Reused Elements

You can change a reused element to another element from your warehouse topics.

  1. Open a topic that contains an element reused from a warehouse topic.
  2. Click the reused element.
    The Content reference toolbar appears.
  3. In the Content reference toolbar, click Change .
  4. Click the Select file button.
  5. In the Library dialog, select a warehouse topic.
  6. Select the element that you want to insert in place of the old element by doing the following:
    1. Click the Link Inside File (Select Target Element) button.
    2. In the Create/Edit Link dialog, select the element.
    3. From the list that appears, select the element.
    4. If prompted about the element ID, click OK and Save .
      Tip: easyDITA generates ID values automatically but you can enter your own values. The ID values must be unique. Assigning customized values may boost consistency in your documentation.
    5. Click the Insert Content button.

Remove Reused Elements

Remove a reused element from your topic.

  1. Open a topic that contains an element reused from a warehouse topic.
  2. Click the reused element.
    The Content reference toolbar appears.
  3. In the Content reference toolbar, click Remove .

Navigate Reused Elements

You can check content reference dependencies by using the topic editor.

  1. To check where an element is reused, do the following:
    1. Open a warehouse topic.
      Tip: In the topic editor, the Reuse icon indicates that a given element is reused in other topics. The number that corresponds to the Reuse icon indicates how many times the element is reused.
    2. Click the Reuse icon.
      A list of files that reuse the element appear.
    3. Open a topic that reuses the element by clicking the file title.
      The topic opens in a new tab.
  2. To check from which warehouse topic the element is reused, do the following:
    1. Open a topic that reuses elements from warehouse topics.
      Tip: In the topic editor, the gray background around an element indicates that a given element is reused from other topics.
    2. Click the reused element.
      The Content reference toolbar appears.
    3. In the Content reference toolbar, click Open .
      The topic opens in a new tab.