Use attribute and element values in the map to affect formatting and properties in the structure application, set conditional hide/show settings, and update variable definitions.
DITA-FMx provides a number of features which make it easier to use map-level metadata to control formatting and data in the generated chapter files. Attribute and element values in the map are passed to the fm-ditabook element (the root of the generated book file) during the XSLT import step of the book-build process. Once these attribute values are set on the fm-ditabook element they can control other aspects of the component document formatting and content.
These attributes can be used in various ways in a structure application EDD and template and to set the hide/show state of conditional text. They can also control the value of variable definitions in files that are included in the generated book file.
By default, only a limited set of metadata (attributes and element values) are transferred to the generated book. You can add additional metadata by modifying the Book application EDD, the fmx-book_1.2.dtd file, and the Book application import XSLT file (bookmap2fmbook.xsl), as described in Adding Map to Book Metadata Mappings. The following tables describe the metadata supported in the default files.
| Bookmap metadata (in bookmeta) | If multiple, use .. | fm-ditabook attribute |
|---|---|---|
| publisherinformation/organization | first instance | @pubinfo-org |
| publisherinformation/published/completed/year | first instance | @pubinfo-completedyear |
| publisherinformation/published/completed/month | first instance | @pubinfo-completedmonth |
| publisherinformation/published/completed/day | first instance | @pubinfo-completedday |
| permissions/@view | first instance of permissions | @permissions-view |
| category | first instance | @category |
| critdates/created/@date | first instance | @created |
| critdates/revised/@modified | last instance | @revised |
| bookid/bookpartno | first instance | @bookpartno |
| bookid/edition | first instance | @edition |
| bookid/isbn | first instance | @isbn |
| bookid/booknumber | first instance | @booknumber |
| bookid/volume | first instance | @volume |
| bookid/maintainer/person | first instance | @maintainer-person |
| bookid/maintainer/organization | first instance | @maintainer-org |
| bookrights/copyrfirst/year | - | @copyrfirst |
| bookrights/copyrlast/year | - | @copyrlast |
| bookrights/bookowner/organization | first instance | @copyrholder |
| bookrights/bookowner/organization | first instance | @bookowner-org |
| bookrights/bookowner/person | first instance | @bookowner-person |
| bookrights/bookrestriction/@value | - | @bookrestriction |
| prodinfo/prodname | - | @prodname |
| prodinfo/vrmlist/vrm/@version | last instance | @version |
| prodinfo/vrmlist/vrm/@release | last instance | @release |
| prodinfo/vrmlist/vrm/@modification | last instance | @modification |
| authorinformation/personinfo/namedetails/personname/firstname and lastname | first instance | @authorname |
| Map metadata (in topicmeta) | If multiple, use .. | fm-ditabook attribute |
|---|---|---|
| critdates/created/@date | first instance | @created |
| critdates/revised/@modified | last instance | @revised |
| copyright/copyryear/year | first instance | @copyrfirst |
| copyright/copyryear/year | last instance | @copyrlast |
| copyright/copyrholder | - | @copyrholder |
| author | - | @authorname |
Attribute value building blocks can reference an attribute in the book file (as well as attributes in elements in the same file). Use the following building block to reference the value of the prodname attribute on the fm-ditabook element:
<$attribute[prodname:fm-ditabook]>
Attribute value building blocks like this can be used in cross-reference formats, header/footer variables, as well as EDD prefix and suffix rules. You can also use this type of building block in EDD context rules to apply formatting based on the values of book-level attributes. A context rule could start as follows:
If context is: * < fm-ditabook[prodname="DITA-FMx"]
Note that changing an attribute value directly in the book doesn’t affect the component files until that book is updated.
To enable the setting of conditional text hide/show states using book-level attributes you must be using a book-build INI file for your book building process. If you’re not familiar with the book-build INI file, you should review the information in The Book Build Settings Dialog and the Book-Build INI File. To enable this feature, set the ImportAttrsAsConds parameter to “1” in the General section of the book-build INI file.
When using this feature, conditional text names must follow a specific naming convention of “<prefix><attribute>-<value>”. Where <prefix> is “fmx-” by default, but can be changed by setting the General/AttrAsCondPrefix parameter, <attribute> is the name of the fm-ditabook attribute, and <value> is the value of that attribute. For example, if you wanted to be able to hide/show a condition that was controlled by the value of the bookmeta/bookrights/bookrestriction/@value attribute, you could use conditions named “fmx-bookrestriction-confidential” and “fmx-bookrestriction-restricted”. These conditions must exist in the templates (Book application template and any component templates) and must be set to “Show” (if they are set to “Hide”, any content tagged with that condition will be lost when the template is applied).
To control the hide/show state of a condition, you must add the condition names to the ConditionMap section of the book-build INI file. List each condition name followed by “Hide” or “Show” (typically “Show”).
[ConditionMap] fmx-bookrestriction-confidential=Show fmx-bookrestriction-restricted=Show
When this feature is enabled, DITA-FMx starts off by hiding all “fmx-” conditions (or whatever is defined as your prefix using the AttrAsCondPrefix parameter) in the document. Then, each fm-ditabook attribute and value are matched with the condition named in the ConditionMap section. If a match is found (using the “<prefix><attribute>-<value>” naming convention), that condition is set to the specified hide/show state. The fm-ditabook attribute value set in the bookmap must be represented by a condition specified in the book-build INI, so be sure to include all possible condition names that you're hiding and showing and set them all to “Show” (even if some may need to be hidden). Only one value for an attribute can be set at a time, so only the condition representing an attribute value match will show.
If you need to work in reverse and have all of the conditions set to “Show” by default, you can set the General/AttrAsCondDefaultState parameter to “Show”, then set the values in the condition map to “Hide”.
This condition setting works in both generated (structured) FM files as well as unstructured FM files (from generated lists as well as those files that have been “included” via the book-build INI).
To enable the updating of variable definitions using book-level attributes you must be using a book-build INI file for your book building process. If you’re not familiar with the book-build INI file, you should review the information in The Book Build Settings Dialog and the Book-Build INI File. To enable this feature, set the ImportAttrsAsVars parameter to “1” in the General section of the book-build INI file.
If the ImportAttrsAsVars parameter is set to “1”, all fm-ditabook attributes are used to update like-named variables in each book component (both structured and unstructured files). Like the conditional text names, the variable names must adhere to the naming convention of “fmx-ATTRIBUTE-NAME”. The value of the variable is set to the value of the fm-ditabook attribute.
In order to make use of these map-defined variables, create a variable definition of the proper name (following the naming convention described above), give it some default value, then insert it into the document. If you’re using this in a structured application template file, you’ll be placing this variable in a frame that’s not part of the main flow (since the flow is replaced with the XML-defined data). If this is being used in an unstructured file that is being included (using the IncludeFiles book-build INI feature), you can place the variable wherever it makes sense to do so.
After the book has been generated and updated, the variables will have been updated with the values from the map.
For example, if your goal is to include a header/footer variable in your documents that includes the “version” information defined in the DITA map metadata.
In your DITA map, include a prodlist/vrmlist/vrm/@version value.
In your Book application template file, or in the appropriate component template, add a header/footer variable named “fmx-version” and give it a default value (perhaps “0.00”). Save and close the template file.
You can also add this variable definition to any “included” FM binary files. The variable value will be updated when the book is generated.
In your book-build INI file (or the default book-build INI), enable the ImportAttrsAsVars parameter by setting it to “1”.
Use the Generate Book from Map command to create a new FM book and chapter files. The pages in the generated output that are based on the template pages which include the variables added in step #2 will contain the updated variable values.
This works because the Book application’s XSLT file creates the corresponding attribute (@version in this case) on the fm-ditabook element (in the generated book file). If this isn’t working, make sure that your Book application XSLT contains the proper variable definition, and you’ve followed the instructions correctly.
You should be able to create variables that use any of the fm-ditabook attributes listed in the tables in Passing Map-level Metadata to the FM Book. If you want to make use of map metadata not currently supported by the XSLT, just add new XSLT variable processing for a new fm-ditabook attribute and add that attribute definition to the fmx-book_1.2.dtd file and to the Book application EDD.