• 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

Conkeyrefs

Posted on 12.02.16

Advanced reuse in DITA Lesson 3: Advanced conrefs Conkeyrefs

A conkeyref is a content reference that uses a key instead of a file path. As described in the Introduction to reuse in DITA course, a content reference to an element in another file might look like this:

<ul conref="domestic_duck_warehouse.dita#domestic_warehouse/nesting_materials">
   <li/>
</ul>

This conref pulls a <ul> element from a warehouse topic that contains reusable elements relevant to domestic ducks.

If the topic containing this conref must be reusable, a hard-coded filename will be a problem. To use the reusable topic in a map that discusses wild ducks, the conref needs to point to a different warehouse topic file (wild_duck_warehouse.dita).

Rather than hard code the path to a file, you can use the conkeyref attribute to create a content reference that uses a key, rather than a filename.

The first step in using a conkeyref is to create a DITA topic (domestic_duck_warehouse.dita) that contains a reusable element (including an id attribute):

<ul id="nesting_materials">
   <li>Sawdust</li>
   <li>Wood shavings</li>
   <li>Sand</li>
   ...
</ul>

In a map that references the topic that will use the conkeyref, define a key for the warehouse file:

<keydef keys="duck_warehouse" href="domestic_duck_warehouse.dita"/>

The example at the beginning of this topic shows a <ul> element with a conref. Replace the conref attribute with a conkeyref attribute that contains the key, a slash (‘/’), and the id of the element to be pulled:

<ul conkeyref="duck_warehouse/nesting_materials">
   <li/>
</ul>

Note: When using conkeyrefs you do not need to use the id of the topic that contains the referenced element.

When the topic containing the conkeyref is processed, the key duck_warehouse is replaced with the current key definition, which is domestic_duck_warehouse.dita.

You can reuse the topic containing the conkeyref in another DITA map, but you might need it to pull content from a file that is specific to the new map. To do this, add a <keydef> element to the new map that defines the key so that it points to a different file. In this example, the new map (that addresses wild ducks) defines the duck_warehouse key to point to wild_duck_warehouse.dita:

<keydef keys="duck_warehouse" href="wild_duck_warehouse.dita"/>

The file wild_duck_warehouse.dita defines a different <ul> element; however, it must use the same id attribute:

<ul id="nesting_materials">
   <li>Ferns</li>
   <li>Twigs</li>
   <li>Grass</li>
   ...
</ul>

When this new key is used in the wile duck map, the unordered list of wild duck nesting materials is used.

Finally, note that all the same rules that apply to conrefs also apply to conkeyrefs:

  • The referencing element must be the same type (element name) as the referenced element.
  • The referencing element must be valid (for instance, a <ul> element must contain at least one <li> element).
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}