Skriftlig Info ➜ DITA publishing ➜ Indirect adressing ➜ Use the conkeyref attribute to fetch a single text element
Indirect adressing
Introduction to indirect adressing
Why should I use indirect adressing?
Buildingblocks in indirect adressing
Illustrating the indirect adressing sequence
Use the keyref attribute to fetch an entire topic
Use the conkeyref attribute to fetch a single text element
If you are used to working with topic libraries, you know that you can insert any¹ element from a library using the conref attribute. This way of reusing text elements offers enormous savings in time and money, especially if you need to translate your publications. In indirect addressing, we replace the conref attribute with the conkeyref attribute.
(¹) I say "any element", but that may not be true for everybody. You can only reuse elements identified with an id attribute. You may need to configure this attribute in your DITA system.
The conkeyref attribute will fetch a single text element from the source topic and place it in your tareget topic. Which element to insert is controlled by the element in your target topic and the keymap. This means that if you use the same topic in two different publications, you can still benefit two different contents.
This feature is very useful in project and product publications that are large and complex. Such manuals will often require extensive work with the infrastructure: assembling topic maps and relationship tables. The conkeyref attribute allows replacing single text elements in your topics without changing this infrastructure. You can also use this functionality to reuse the text elements. This functionality increases the reuse and reduces your workload.
|
In this context, a text element can be any DITA element that contains multimodal text. It can for example be a <p> element that contains one or two sentences. It can also be a <div>, <sectiondiv> or <section> element that contains a lot of information. The configuration of your DITA system determines which element you can use. |
The official DITA specification explains the conkeyref attribute like this:
The @conkeyref attribute provides an indirect content reference to topic elements, map elements, or elements within maps or topics. When the DITA content is processed, the key references are resolved using key definitions from DITA maps.
For content references from map elements to map elements or topic elements to topic elements, the value of the @conkeyref attribute is a key name, where the key must be bound to a map element (for references from map elements) or a topic element (for references from topic elements). For all other elements, the value of the @conkeyref attribute is a key name, an optional slash ("/"), and the ID of the target element, where the key name must be bound to the map or topic that contains the topic element.
Oasis: The @conkeyref attribute, http://docs.oasis-open.org, [REF]
If you want to explore the additional features provided by the key-based indirect addressing features, I suggest you start with the DITA specification.
The keymap uses the <keydef> to make the connection between the target topic and the source topic. The official description from the DITA specification can be found here:
You don't need to do anything in your topic map. The target topic is already there using a direct address:
<topicref href="URI">
"URI" is the Uniform Resource Identifier that provides a unique address to the topic.
The target topic is created just like any normal DITA topic. If you use library topics, text elements are inserted using the conref attribute:
<div conref="ID">
I have here chosen to insert a <div> element from a library. The conref attribute links directly to the source topic and the <div> element inside the source topic. In this case, the ID (identifier) is a long text string made up with several URI elements.
When you want to employ indirect addressing, you must use the conkeyref attribute.
<div conkeyref="NAME/ID">
This is the key request.
In this example, the conkeyref attribute contains the single word "NAME", then a "/" character followed by an identifier (ID). I have chosen both the single word and the identifier (ID). I can use any words I want. However, they must be unique in my publication.
So the big question here is: Where does the conkeyref attribute value "NAME/ID" take me?
While your topic maps are reused in many publications, the keymap is unique for each publication. This means that the "rotary switches" in the keymap are set to specific source topics. The <keydef> element is used to set this switch based on the key request it receives from your topic map.
The <keydef> element is used to make the connection:
<keydef keys="NAME" href="URI">
"URI" is the Uniform Resource Identifier that provides a unique address to the source topic.
|
The ID in the key request is not used by the keymap. However, in the source topic identified by the URI, my chosen ID must match a similar element using the same ID. |
My source topic must be set up to match the element and the ID in the key request.
|
If my key request is submitted by a conkeyref attribute in a <div> element, my source topic must provide a <div> element identified with the same ID provided in the key request. |
This means:
<div conkeyref="NAME/12345">
...in the target topic must find...
<div id="12345">
...in the source topic.
Remember, the "NAME" component was used by the <keydef> element in the keymap to direct you to the correct source topic.
I am using a <div> element in this example, because I find this element to be truly versatile. I use it a lot as a neutral "container". The configuration of your DITA system determines which element you can use.
TipEven if several target topics provide key requests, you can do so with only a single source topic. The number and type of source topics depend on the elements you use in the target topics. With generic elements such as a <p> or a <div> you can place the source elements together in a large concept or reference source topic. However, if you use elements specific to task topics, such as <context> or <step>, your source topic must also be a task topic. |
All external links open in a new window. I take no responsibility for information on external websites, even if I have linked to them. Please report links that do not work.
The information on this page represents my personal opinions and my understanding of the topic being described. Feel free to link to the page, but do not copy large parts of the content without permission. I take no responsibility for any errors, misunderstandings or missing information. I also take no responsibility for any mistakes you may make or cause as a result of incorrect or missing information. You are welcome to contribute with comments, relevant experiences or additional information. See Editor and contact information.