Developing Custom Structure Applications

Once you’re comfortable with the features in DITA-FMx, you’ll surely want to create your own custom structure applications that apply your house style to your DITA documents.

In FrameMaker, all of the formatting and page layout applied to XML files is done by the selected structure application. A structure application (also called a “structure app” or just “app”) is made up of the following components:

Template file – contains the page layout, paragraph/character formatting, other object formatting (such as cross-ref and variable definitions), and any document-specific interface defaults (such as the visibility of element boundaries).
EDD (element definition document) – defines the structure of the elements in the data model, and the context rules for formatting those elements.
DTD (document type definition) files – a set of markup declarations that define a document type for SGML-based markup languages (XML, SGML, HTML). This includes files of type DTD, ENT, MOD, and others that define the structure of a data model.
Read/write rules file – specifies how FrameMaker translates from markup (XML files) to the authoring environment and back.

There are many ways to develop and maintain structure applications. DITA-FMx is set up to work with three types of apps, a Topic app and a Map app (both used for authoring) and a Book app (used for printing and PDF generation). If you want to control the way your DITA files are printed, you will want to modify the Book app. If you want to modify the structure or add/remove elements, you’ll need to modify both the Topic and Book apps (and possibly the Map app). The default DITA-FMx application folder structure puts the files for all three of these apps into Topic, Map, and Book folders under a main folder named “DITA-FMX_1.1.” We find this folder structure to be the most efficient, but you are free to devise any structure that works for your needs.

When creating your own custom structure applications, you can either start by cloning the existing default DITA-FMx apps or by creating your own from scratch. The cloning method is the easiest and least likely to have errors, but you can do which ever works best for you.

You may be tempted to make minor modifications to the default DITA-FMx apps. We strongly recommend that you maintain an instance of the DITA-FMx structure applications in their original form. Because these applications work properly with DITA-FMx, as you customize/build your own apps, you may need to refer back to the originals in case something goes wrong (which it often does).

Note: The EDD files provided with DITA-FMx are in MIF format by default. This results in the installer application being 8 MB smaller in file size than it would be if we provided the EDDs as FM binary files. If you plan to modify the EDDs in any way, you should save them as FM binary files before making any modifications. After saving as an FM binary, feel free to delete the MIF files.

Cloning the Default Structure Applications
The first step in customizing the layout or formatting of a structure application is to create your own application; the easiest way to create your own is to clone the existing apps.
Customizing the Formatting in the Default Structure Applications
When customizing or localizing a structure application, changes need to be made to the paragraph and character formatting applied to elements by that application. Locating the files that define this formatting may not always be easy.
Adding New fm-ditabook Attributes
Passing data from a DITA map to the generated FM book file can be accomplished by creating new attributes on the fm-ditabook element.
Required Element Definitions
To make the most of the authoring and publishing features in DITA-FMx, some elements must be set up in a specific manner. This topic describes those requirements.