In the previous post, I explained how the proper product-specific image can be automatically picked up and included into the publication using the key reference mechanism instead of conditional filtering.

Today I want to give you another example of how you can use a mechanism, called content key reference, to include a product-specific piece of content required for a particular output.

Let’s keep using the scenario with three printer models, which we used in the previous post – EasyPrint Basic, EasyPrint Pro, and EasyPrint All-In-One. Imagine that we have now a procedure that explains how to make a copy. This topic is relevant for Pro and All-In-One only. Steps 1 through 3 are common for the both models, but step 4 is different for different models:

EasyPrint Pro


EasyPrint All-In-One


Perhaps the easiest solution would be keeping both steps in the topic and using a conditional attribute, like @product, to markup the differences:


As long as you have just two products, this approach works fine. But if the company is doing well, the number of products tend to grow overtime. This means that the amount of conditions and complexity of their possible combinations (for example, a step might be relevant for Product A and Product B and Product C and Product D while the next step is relevant for Product B and Product C and Product E) will grow too.

Fortunately, DITA provides a mechanism called content key reference (conkeyref). It works in the same way as a regular conref in the sense that a piece of content is pulled from topic (source) to another one (target). The difference is that with conkeyref, you don’t refer to the source topic directly using the path and file name. Instead, you are referring by an alias, known as key. Then you resolve the key into the actual file name in the map.

In our example, instead of adding all product-specific steps and profiling them, we create a separate topic for each product. Each of these topics will hold the product-specific step:

  • MakingCopy_Pro.dita will contain the step for EasyPrint Pro.
  • MakingCopy_All-In-One.dita will contain the step for EasyPrint All-In-One.

Notice that just like in a regular conref source, the step to be pulled has an ID set to “product_specific_copy”. This ID is identical for the step of the both products.





Now we can add a conkeyref to the Making a Copy topic. It will work as a placeholder for the product-specific step:



As you can see, the conkeyref consists of two parts:

  • product_specific_step is the alias (or key) of the source topic that holds the step for the particular model. We’re going to resolve the key into the actual file name in the map.
  • product_specific_copy is the ID of the step that we are going to pull. We’ve defined in MakingCopy_Pro.dita and MakingCopy_All-In-One.dita.

In the map, we can resolve the key “product_specific_step” to the actual file name, depending on the output you want to generate. If you have a separate map per product, then you specify the file name of the source file differently in each map.





That’s it! Now you have a single placeholder in the Making a Copy topic that will be dynamically replaced with the step taken from either MakingCopy_Pro.dita or MakingCopy_All-In-One.dita depending on the map that you are publishing.

This approach does require more planning and more setup work than traditional conditional content, but considering that the amount of conditions tend to grow overtime, using conkeyref can significantly facilitate content maintenance in the long run.





Leave a Reply

Your email address will not be published. Required fields are marked *