Conref push (conaction)

Advanced reuse in DITA Lesson 3: Advanced conrefs Conref push (conaction)

When a topic uses a content reference, content is “pulled” from the referenced topic into the referencing topic. However, there are times when you need to insert an element into an arbitrary location of a reusable topic.

For instance, you might have a reusable topic that does its job well most of the time when it is used. However, in one case (for one product, or for one customer), you need to add an extra paragraph to that reusable topic. One solution might be to add the paragraph and use conditional filtering to only display the paragraph for that one use. But what if you don’t own (or have the rights to modify) the reused topic? What if the reused topic is maintained in a publicly visible area (say on GitHub), and you don’t want your addition to be visible to the rest of the world?

The conref push (or conaction) mechanism allows you to “push” content from one topic in a map (the source topic) into another topic in the same map (the target topic).

The conref push mechanism allows you to push in three ways. You can push an element so that it:

Is inserted before a specific element.
Replaces a specific element.
Is inserted after a specific element.

Just as with a normal conref operation, the source and target elements used in the conref push must be the same type.

To use conref push you need to do three things:

Make sure that the target element (the element you want to push your element before, after, or in place of) has an id attribute.

For example, to push an element before, after, or in place of this element, it must have an id:
```
<p id="install_intro">This chapter describes how to install and configure the Duck Database on Windows and Macintosh.</p>
```
Create a DITA topic containing the element to be pushed.

The topic should contain all necessary elements to make sure that the element being pushed is valid. So, if you need to conref push a <li> element, your topic should contain a <body> (depending on the topic type), a <ul> element, and the <li> you need to push.

The actual content and attributes of the element being pushed are described in the sections below.
Add a <topicref> element to your map that points to the topic containing the element to be pushed.
```
 <topicref href="c_conrefpush_sources.dita" processing-role="resource-only"/>
```
Note that this <topicref> element must use processing-role=”resource-only” because the content should not appear in normal map order in the output.

The following sections show how to use conref push to replace an element, insert an element before a target, and insert an element after a target. All the examples use this topic as the target:

<concept id="c_install">
 <title>Installing Duck Database</title>
 <conbody>
  <p id="install_intro">To install the Duck Database on Windows and Macintosh, follow these instructions.</p>
  <p>If at any time you need help in the installation process, please call our 24-hour hot line.</p>
 </conbody>
</concept>

Output from this topic, without any conref push looks like this:

Note: The DITA sources shown in these examples are in the downloadable samples file reuse_advanced_samples.zip. The target DITA file is c_conrefpush_target.dita; the source DITA file is c_conrefpush_target.dita.

Replacing the target element

To replace an element in the target topic, use the element’s conref attribute to identify the element to replace, and set the conaction attribute to “pushreplace”:

<concept id="c_conrefp_source">
 <title>Conref push sources</title>
 <conbody>
  <p conref="c_conrefpush_target.dita#c_install/install_intro" conaction="pushreplace">
   To install the Duck Data base on Windows, follow these instructions. </p>
 </conbody>
</concept>

The output from the target topic now looks like this:

Inserting an element before the target element

To insert the element before the target element, you use two elements (both must be the same as the target element):

The first element uses the conaction attribute set to the value “pushbefore” and contains the content to be pushed.
The second element doesn’t contain any content but uses both the conref attribute (to identify the target element) and the conaction attribute set to the value “mark”.

This example shows the two <p> elements:

<concept id="c_conrefp_source">
 <title>Conref push sources</title>
 <conbody> 
   <p conaction="pushbefore">
   Make sure you have performed the pre-configuration steps. 
   </p>
   <p conref="c_conrefpush_target.dita#c_install/install_intro" conaction="mark"/>
 </conbody>
</concept>

The output from the target topic now looks like this:

Inserting an element after the target element

To insert the element after the target element, use the same two elements, but the element containing conref and conaction=”mark” must come before the element containing conaction=”pushafter”:

<concept id="c_conrefp_source">
 <title>Conref push sources</title>
 <conbody> 
    <p conref="c_conrefpush_target.dita#c_install/install_intro" conaction="mark"/>
    <p conaction="pushafter">To install on Ubuntu, see the subsequent section. </p>
 </conbody>
</concept>

The output from the target topic now looks like this: