• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Learning DITA

Free DITA training

Free DITA training

  • Log in
  • Register
  • Newsletter
  • Profile
  • Privacy
  • Home
  • About
  • Courses
  • News
  • Resources
    • Recordings
  • Questions?
  • Contact

Conref push (conaction)

Posted on 12.02.16

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):

  1. The first element uses the conaction attribute set to the value “pushbefore” and contains the content to be pushed.
  2. 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:

Two final notes on conref push:

  • You cannot use the conrefend attribute with the conref push mechanism.

  • You can use the conkeyref attribute to indicate the target of a conref push.

Contributors
  • Simon Bate
  • Jake Campbell
  • Gretyl Kinsey
Previous Topic
Back to Lesson
Next Topic

sidebar

Blog Sidebar

  • Scriptorium logo
    Maximize the value of your content. Read more.
  • Scriptorium logo
    Already in DITA and need support? Contact us.
RSSLinkedin

Want to add content? Join the ditatraining GitHub repository.

  • Home
  • News
  • Contact
  • Privacy
  • Cookie Policy

Maintained by Scriptorium Publishing

Logo and site presentation © 2015–2023 Scriptorium Publishing. Content based on the open-source DITA training project.

Manage Cookie Consent
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent, may adversely affect certain features and functions.
Functional Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes. The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
Manage options Manage services Manage vendors Read more about these purposes
View preferences
{title} {title} {title}
Manage Cookie Consent
To provide the best experiences, we use technologies like cookies to store and/or access device information. Consenting to these technologies will allow us to process data such as browsing behavior or unique IDs on this site. Not consenting or withdrawing consent may adversely affect certain features and functions.
Functional Always active
The technical storage or access is strictly necessary for the legitimate purpose of enabling the use of a specific service explicitly requested by the subscriber or user, or for the sole purpose of carrying out the transmission of a communication over an electronic communications network.
Preferences
The technical storage or access is necessary for the legitimate purpose of storing preferences that are not requested by the subscriber or user.
Statistics
The technical storage or access that is used exclusively for statistical purposes. The technical storage or access that is used exclusively for anonymous statistical purposes. Without a subpoena, voluntary compliance on the part of your Internet Service Provider, or additional records from a third party, information stored or retrieved for this purpose alone cannot usually be used to identify you.
Marketing
The technical storage or access is required to create user profiles to send advertising, or to track the user on a website or across several websites for similar marketing purposes.
Manage options Manage services Manage vendors Read more about these purposes
View preferences
{title} {title} {title}