Passing Map-level Metadata to the FM Book

In DITA-FMx 1.1.09 a number of features were added to make it easier to use map-level metadata in the generated book and chapter files. Attribute values on the fm-ditabook element (the root of the generated book file) can be used to set the values of variables, and to set the show/hide state of conditional text in the generated chapter files. Attribute values at the book level can also be used by running header/footer variables as well as element definition context rules.

By making fairly simple modifications to the import XSLT that is part of the Book structure application, you can extract element and attribute values from the map and apply them to the fm-ditabook element as attributes. The default import XSLT file (as of DITA-FMx 1.1.09) contains some sample code that can be copied to include additional map data. The sample code is included in the map and bookmap templates and is marked with the XML comments, “custom topicmeta/bookmeta data passed to fm-ditabook attributes.” When adding new attributes to the fm-ditabook element, you must also add those attributes to the fmxbook.dtd file and the Book EDD (then import that EDD into the template).

The default XSLT file includes code to add the creation and revision dates from the map into the generated book file. In the first block below, the XSL code below creates an attribute named “created”, then uses the value of the date attribute of the first “critdates/created” element. In this case specifying the “first” element is not completely necessary since there can only be one, but it’s a good practice to set up your code to select the first (or last) element since you don’t want to add two attributes of the same name. The second block creates a “revised” attribute with the value of the modified attribute from the last “critdates/revised” element.

<xsl:attribute name="created"> 
    <xsl:value-of select="//critdates/created[1]/@date"/> 
</xsl:attribute> 
<xsl:attribute name="revised"> 
    <xsl:value-of select="//critdates/revised[position() = last()]/@modified"/> 
</xsl:attribute>

With these additions, the fm-ditabook element will have two attributes, created and revised, that contain the values of the like-named elements in the map. These values can be accessed and used by context rules in the EDD or by header/footer variables in the chapter files of the book. They can also be used as variables in included binary files or generated list files (TOC, Index, etc.) if the General/ImportAttrsAsVars parameter is set to “1” in the book-build INI file.

Another feature allows you to leverage these attribute values to specify the show/hide state of conditional text. Setting the General/ImportAttrsAsConds book-build INI parameter to “1” enables this feature. Then you need to set up a ConditionMap section which contains a mapping of condition descriptors and the show/hide state. A condition descriptor follows a specific naming convention which starts with “fmx-” and is followed by the attribute name and value separated by a hyphen. For example, if you wanted to be able to control the show/hide state of a condition that exposed some information available only to beta testers, you might set up an othermeta attribute named “docstate” with a value of “beta”. You would modify the XSLT to pass that value into the book as an attribute named “docstate” and the condition map section would be as follows:

[ConditionMap] 
fmx-docstate-beta=Show

The “fmx-docstate-beta” condition must exist in the structure application template prior to running the book build process. The default state of this condition would be “Hide”, but when the map has othermeta/@name=’docstate’ set to “beta” the condition would be set to “Show” instead.