One Content – Many Layouts! Automatic Master Page Assignment in Adobe FrameMaker

This is a small recap to my webinar with Adobe in November 2016. There I explained how to manage different layouts with the same content. In this blog post, I want to summarize the main parts of this event and bring up some more facts. For those of you who like the webinar format, the recording is still available. Have fun!

Since many years, starting with FrameMaker 7.0, a function called Apply Master Pages is available within FrameMaker. In my daily work as a trainer, developer and system integrator I notice again and again that this powerful feature is not a matter of common knowledge. I noticed that people often do a lot of heavy things like scripting or other strange workarounds to get results which can be achieved very easy with no (or a little bit of) scripting. The magic is in your document templates.

I prepared some sample data for this webinar. We captured unstructured and structured binary documents as well as XML based documentation. Sample data is based on the Sample User Guide shipped with Adobe FrameMaker, contains scripts, a structured application with some XSLT stuff and of course FrameMaker and XML documents. Download nearly 80 MB of data and do with it whatever you like.

In this Blog Post

Automated Master Page Assignment with Unstructured Documents

You need three things to make use of master page assignment in unstructured environments:

  1. A FrameMaker template (I’m sure you have one)
  2. Master Page Map called UnstructMasterPageMap on your reference page
  3. One small ExtendScript which provides context information to your unstructured data.

Configuration for unstructured documents

Step 1: Add Master Page Map to your Template

In case of your template doesn’t contain a master page map already, simply open your template and execute Format > Page Layout > Apply Master Pages. A message confirms that the map was added to your template. Go to the last reference page in your template with View > Reference Pages and see what happened.

You got a new Reference Page called MasterPageMaps and a table like the above but without content. Now you can start to configure your master page assignment rules.

Step 2: Configure your Master Page Map

Look at the master page map in figure Configuration for unstructured documents. You see that you are able to control your assignments by paragraph formats. Start with the most common rules at the beginning of the table and let more specific rules follow in rows below.

The first four blue rows are the rules which are already shipped with the FrameMaker sample. Depending on the four paragraph formats there are four different pages assigned in a double paged layout.

Then we start to override this shipped rules for two further layouts: one for Adobe (red) and one for practice innovation (orange). Our template has different paragraph formats for headings and for each layout we want to produce. With these specific heading formats we are now able to control the master page assignment. We assign different covers, different section covers and different content pages.

Note

If you are in a single page layout, just leave column Left-Handed Master Page empty.

Step 3: Applying Master Pages

If you finished your configuration, it’s quite easy for you and your colleagues, to apply these different layouts. Just select Layout > Page Layout > Apply Master Pages. But before that, you have to change the heading formats.

Why do we a need a script?

And exactly this is the point where the script comes in. In documents or books with hundreds of pages, it is a lot of manual work and prone to errors to assign all these styles. The script in our sample data does this job for us, and, of course, it executes the function Apply Master Pages automatically.

Unfortunately within unstructured documents we do not have more than paragraph format to control the layout. So we have to solve this issue with different paragraph styles and need some additional functionality for automation.

Alternatives – Why not simply use different templates?

This is a sample to illustrate the functionality and to show differences between unstructured and structured content. Of course, you can use different templates to manage these kind of different layouts. But you always need at least the first four rules in our master page map to fulfill automation requirements.

And: always keep in mind, multiple templates mean more administrative overhead. One template is easier to maintain and to keep consistent. It’s not uncommon people manage lot of templates and this could be an approach to minimize such overhead. It’s up to you to find the right balance.

And: it’s also important to know that the maximum amount of master pages is 99. So in certain situations and due to this restriction it is necessary to work with more than one template.

Automated Master Page Assignment with Structured Documents

To achieve the same result as before, we only need to things. We don’t need any script and are able to cover all this stuff without programming:

  1. We need a FrameMaker template which embeds an Element Definition Document (EDD) (I’m sure you have one, when you are working with structured documents).
  2. We need a Master Page Map called StructMasterPageMap on the reference page

Configuration for structured documents

Step 1: Add a Master Page Map to your Template

Generating a missing reference page and applying them in a certain context is the same than with unstructured documents, so I skip the explanation for these two points here.

We are using the same content. But I have enhanced this with structure information; an EDD. Please see the sample document in zip-file folder structured for the structure, elements used and for more details. Please have a look at the EDD to see how to define different formats, context labels and more.

Step 2: Configure your Master Page Map

It’s not hard to find out the difference in this map between that for unstructured documents. You have got three columns more and you can work with element names, certain attribute values and a context, which is set within the EDD depending on the paragraph’s context.

If you remember, in our unstructured sample, we need to define special styles to get different layouts. With structured documents there is no need to do this anymore. We are able to control heading layout within the EDD with (rule based) format overrides and more important: we enhanced our content with meta information. Each paragraph is mapped to an element and each element is part of an hierarchy, and this is what structured content means, enhance your content with further information.

As now we have attributes and hierarchical context information in addition to an element/paragraph, we can make use of this additional information within our master page map.

Root Element of our Document

As seen in figure above, our root element called Document has an attribute called OEM which defines a selection of three possible values: default (for our default layout), adobe for the red Adobe layout and pi for the orange practice innovation layout. With these three values, we fit the entire layout requirements.

We have to define a context label in the EDD (see following figure) and add this context labels to our master page assignment rules.

Setting Context Label within the EDD

Step 3: Applying Master Pages

If you finished your configuration, it’s quite easy for you and your colleagues, to apply these different layouts. Just select Layout > Page Layout > Apply Master Pages. But before that, you have to change the heading formats.

That’s it. No need for scripting. Context Information brings up this Magic

Why are Context Labels used here?

We can only work with attributes and their values, when they are part of the element we named in first column. As I want to change the entire layout of this document, I defined the OEM attribute at root level of the document. So changing this attribute value has only to be made at this single point and applying master pages brings the result we want to have.

But we are not able to query the root element with XPath or other instruments within the master page map. We have to set context information out of our hierarchy, and this is where the EDD and context labels come in.

Automated Master Page Assignment With XML Documents

One Second: If you read the text above carefully, I told you, that you can have multiple layouts without changing the content. Until here, it was only 21; the half truth. Of course, we didn’t change the content, but we made big or at least small changes to the document “structure”. We changed paragraph formats or an attribute and that makes the “new” document different.

And now we are on our way to Number 42. We won’t manipulate our documents. And we will achieve this by separating content and layout or better by separating content creation and publishing processes.

Furthermore we are enhancing our requirements for pi-layout. Each chapter of our publication has to get its own thumb tab at a different position than the chapter before.

To achieve our requirements, the old and new ones, we need three things:

  1. A FrameMaker template which embeds an EDD (same as before).
  2. The Master Page Map called StructMasterPageMap on your reference page (same as before but enhanced for the new requirements).
  3. Structured applications which enable us to load XML files into FrameMaker (I’m sure you have one, if you are working with XML files).

Configuration for XML documents

Step 1: Add a Master Page Map to your Template

Generating a missing reference page and applying them in a certain context is the same than with unstructured documents, so I skip the explanation for these two points here.

We are using the same content. But I have enhanced this with structure information; an EDD. Please see the sample document in zip-file folder structured for the structure, elements used and for more details. Please have a look at the EDD to see how to define different formats, context labels and more.

Step 2: Configure your Master Page Map

To fulfill the new and the old requirements, we have to setup 1+3 XML applications. One application is used for editing our content. The other three are used to publish this content to three different layouts which results in three different FrameMaker books with binary documents, table of contents and other generated lists.

All three publication applications look the same with one small difference. Have a look in XML application pi Book OEM PI. There is a reference to an XSLT-stylesheet, which is applied, before an XML file is opened in FrameMaker (PreProcessing). This stylesheet defines a parameter called oemType and implements rules for default, pi and Adobe layout. If you are opening the book.xml file from our sample data in FrameMaker you are prompted to select one of these three application. This is your choice to select the target layout you want. After selecting the application FrameMaker generates a FrameMaker book and a FrameMaker document for each chapter.

Note

If you open a content XML file, it is opened with the fourth application and no changes are made to it by the process.

When opening book.xml file in FrameMaker an XSLT-stylesheet is called and depending on your selection a parameter oemType is given to the XSLT-stylesheet. Depending on this parameter attribute OEM on root element level is set to fulfill the requirements, we already implemented these rules with solution before. Furthermore it calculates the chapter number and adds it to an attribute named Register. As seen in figure above, we are using this attribute and its value to define specific master page assignment rules for the pi layout.

What does the XSLT-stylesheet do in detail?

As mentioned it calculates the chapter number and puts this into an attribute called Register. Furthermore it generates a label and puts it to an attribute named Label, which should appear on top of the thumb tab (implemented by a specific system variable on master page).

            
<xsl:template match="MainChapter | Contact | Legal">
    <xsl:param name="docRef"/>
    <xsl:element name="{name()}">
        <xsl:apply-templates select="@*"/>
        <xsl:variable 
            name="regCount"
            select="count($docRef/preceding-sibling::*)"
        />
        <xsl:if test="$regCount &gt; 2">
            <xsl:attribute name="Label">
                <xsl:text>Chapter </xsl:text>
                <xsl:value-of select="$regCount - 2"/>
            </xsl:attribute>
            <xsl:attribute name="Register">
                <xsl:value-of select="$regCount - 2"/>
            </xsl:attribute>
        </xsl:if>
        <xsl:apply-templates/>
    </xsl:element>
</xsl:template>

All other lines of these small 111 lines XSLT-stylesheet are mostly standard stuff. Except the generated processing instructions for generating FrameMaker binary books and documents.

            
<!-- [...] -->
<xsl:processing-instruction name="FM">
    <xsl:text>book </xsl:text>
</xsl:processing-instruction>
<!-- [...] -->
<xsl:processing-instruction name="FM">
    <xsl:text>document </xsl:text>
    <xsl:number 
        value="count($docRef/preceding-sibling::*)"
        format="01"
    />
    <xsl:text>_</xsl:text>
    <xsl:value-of select="name(*[1])"/>
    <xsl:text>.fm </xsl:text>
</xsl:processing-instruction>

Your original XML file is not affected

Why doesn’t this effect the original XML file? FrameMaker transforms source files with XSLT-stylesheets defined as pre-process in-memory. It doesn’t save it back to file system, except you add processing-instructions for generating FrameMaker binary files. In this case source file is not changed but the result of transformation is saved within the binary results.

Conclusion

FrameMaker master page assignment is really powerful, as you could see with these small samples here. But you can also use this feature to change page orientation within the text flow, handle different master pages for different languages, changing layout for different chapters like references, tasks. Further things are possible.

And perhaps I could give you a small impression why structured content gives you more possibilities (not only) with your publishing processes.

Have a look at the scripts and XSLT-stylesheet and the EDD as well. You will see, automation is not that hard as you thought.

Looking forward to your thoughts. Let me know what kind of layout issues you have, perhaps some of these can be solved with this or similar features.

Workshop by Markus Wiedenmaier at “tekom Frühjahrstagung” (6.-7. April 2017)

If you are attending the tekom-Frühjahrstagung 2017 (Germany, Kassel, 6.-7. April 2017) you might also want to go to Markus’ workshop Ein Inhalt – verschiedenste Layouts – mit Adobe FrameMaker on Thursday (16:30 – 18:15) or Friday (09:00 – 10:45).