The conref push technique

The conref push technique allows content from a source topic to be inserted into another topic, without any special code in the topic where the content will be re-used.

The normal method of using content references is to reference, in the conref attribute of an element in a topic, the element in a source file that you want to re-use, and pull in that element's value.

In DITA 1.2, an alternative method of content referencing was introduced, allowing the value of an element to be pushed, or injected, from the source element into a topic where it is to be re-used. This technique is known as conref push.

A scenario in which conref push would be useful would be where a car manufacturer produces driver manuals that are customised by the local car dealer before printing. The customisation might simply involve inserting paragraphs with local contact details. The dealer would not want to modify the manufacturer-supplied content, because otherwise those changes would have to be repeated when the manufacturer modified the content.

The conref push mechanism requires elements in the target topic (the topic where the content is to be pushed) having id elements, as the push mechanism inserts elements before or after a named element, or replaces the named element.

For example, there might be a need to insert dealer contact details between these two paragraphs:
<p id="regular_servicing">You should have your car serviced regularly.</p>
<p>The service intervals...</p>

The paragraph to be injected would be maintained in the topic where conref source elements are stored. To push the paragraph, a conref attribute and a conaction attributes must be specified; the conref attribute is a reference to the point in the target topic where the content is to be pushed, and the conaction nominates whether the element is injected before, after, or replaces the referenced element. If the conref source topic is included within a ditamap, the conref push will be processed during publishing of that ditamap.

To confirm that the topic will be valid after the element is pushed, actions that inject content before or after an element require a "dummy" placeholder element of the same type as the referenced element in the conref source topic.

For example, a new paragraph would be inserted after the regular_servicing paragraph with the following code in the conref source topic:
<p conaction="mark" conref="c_servicing.dita#service/regular_servicing" />
<p conaction="pushafter">
  Your local dealer is Snell Performance Vehicles.
</p>
To insert a new paragraph before the regular_servicing paragraph, the following code would be used:
<p conaction="pushbefore">
  You can have your car serviced at Snell Performance Vehicles, your local dealer.
</p>
<p conaction="mark" conref="c_servicing.dita#service/regular_servicing" />
To replace the regular_servicing paragraph, the following code would be used:
<p conaction="pushreplace" conref="c_servicing.dita#service/regular_servicing">
  You should have your car serviced regularly by Snell Performance Vehicles.
</p>
The valid values for the conaction attribute are:
pushreplace
replaces the referenced element with the re-use element
pushbefore
injects the re-use element after the referenced element
pushafter
injects the re-use element before the referenced element
mark
used as a placeholder in the re-use topic when pushbefore or pushafter actions are used