Understanding containers

The DRM implementation is supported by a DITA map specialization called container.

With the DRM module, maps do not contain links to the actual topics. Instead, they contain key references that are resolved by a container file. There is a one-to-one relationship between versions and containers: Each version is associated with a single container and a container is associated with a single version.

The following diagram shows these concepts:

In this diagram, MapA contains 4 topics: a concept and three tasks. The map does not reference the topics directly; instead, each topic is defined with a key. MapA also includes a reference to a container, Container_v1, which includes the key resolution.

Let's illustrate these concepts with a fictional document called the CMS Quick Start. This document has two topics: "About DITA" and "Working with topics". In the standard IXIASOFT CCMS (without the DRM module), this map would be as follows:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd">
<bookmap id="lar1403120614675" xml:lang="en-us">
    <title>CMS Quick Start</title>
    <chapter href="lar1403120714373.xml"/>
    <chapter href="lar1403120831656.xml"/>
</bookmap>

As you can see in the code above, the map references the actual topic files directly using the href attribute. With the DRM module, the map does not reference the topics directly. Instead, it specifies the topics to include using key references. To resolve the keys, the map references a container, which contains the key definitions.

For example, the following code shows the CMS Quick Start map when using release management:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE bookmap PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd">
<bookmap id="lar1403120614675" xml:lang="en-us">
	<title>CMS User Guide</title>
	<containerref href="lar1403119327816.ditamap"/>
	<chapter keyref="lar1403120714373"/>
	<chapter keyref="lar1403120831656"/>
</bookmap>

As you can see in the example above, the topics are referenced with a keyref instead of being directly referenced with an href. The key name is always the ID of the object. The map also includes a reference to a container map. The following code shows the container that resolves the key definitions:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE containerpart PUBLIC "-//IXIA//DTD DITA Container Part//EN" "containerpart.dtd">
<containerpart id="lar1403120655373" xml:lang="en-us">
   <title>3.4.0.1 {0001}</title>
   <keydefs>
      <topicgroup id="Map">
         <keydef href="lar1403120614675.ditamap" keys="lar1403120614675" scope="local"/>
      </topicgroup>
      <topicgroup id="Topic">
         <keydef href="lar1403120714373.xml" keys="lar1403120714373" scope="local"/>
         <keydef href="lar1403120831656.xml" keys="lar1403120831656" scope="local"/>
      </topicgroup>
      <topicgroup id="Image"/>
   </keydefs>
</containerpart>

Containers and container parts

To simplify the explanation, the section above skipped a step in the chain of files required to resolve the keys. In reality, the map for a document points to a container, which in turn points to a container part. The container part is the file that contains the actual key definitions.

The following diagram shows how containers and container parts are defined in the DRM module:

There is a one-to-one relationship between versions and containers: Each version is associated with a single container and a container is associated with a single version. A container can have one or more container parts. Container parts allow projects with many objects to be organized into smaller parts for improved performance. By default, a container part holds 1000 objects (configurable).

The following diagram shows an example of how containers and container parts are used in the fictional CMS Quick Start document. Let's assume that this document is created in version 3.4.0.1 of the CMS product, release 3.4.

As shown above, the CMS Quick Start map points to container 3.4.0.1 and includes two keys, one for each topic that it contains. Container 3.4.0.1 references container part 3.4.0.1 0001, which contains the definition for the keys used in the CMS Quick Start map.

Note that containers, container parts, and keys are transparent to end users, who do not need to understand these concepts to write their documentation.