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.

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

<p conaction="mark" conref="c_servicing.dita#service/regular_servicing" />
<p conaction="pushafter">
  Your local dealer is Snell Performance Vehicles.
</p>

<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" />

<p conaction="pushreplace" conref="c_servicing.dita#service/regular_servicing">
  You should have your car serviced regularly by Snell Performance Vehicles.
</p>