Nested Master Pages

Fragments and Master Pages

If you are designing your forms using fragments, you will likely have done some work to get consistent master page definitions in your final document. The strategy most form authors follow is to define a set of re-usable master pages and include them in their host template.  All included fragment subfoms will then make use of the master page definitions found in the host template.

But what many form authors do not realize is that it is possible for the fragment to bring its own set of master pages into the host document.  The strategy is to define the collection of master pages as a child of the fragment being included.  I have created a sample XDP to illustrate this.  Note in the hierarchy that there are three sets of master pages: one for the root subform, and one each for the group1 and group2 subforms:

In this example, the group1 subform will look up its master page definitions in its nested master page collection. Same for group2.  And if group1 or group2 were to be included as a fragment, their master page definitions would be automatically included, since they’re part of the subform.  If group1 and group2 used the master page definitions defined under form1 and were included as a fragment, they would then use the master page definitions found in their host document.

Referencing Master Pages

Assume we have a master page that is defined with this syntax:

<pageArea name=”Page1″ id=”Page1_ID”>

In Designer, when the pagination option is: ‘ Place: On Page: “Page1″ ‘, the syntax generated by Designer will reference this page by name:


<subform name=”usePage1″>
    <breakBefore target=”Page1″ targetType=”pageArea”/>   

However, we can also reference by id:


<subform name=”usePage1″>
    <breakBefore target=”#Page1_ID” targetType=”pageArea”/>   

Referencing pages by name is the best strategy when you are sharing a global set of master pages. As long as you are consistent in your naming scheme, the “Page1″ referenced by your fragment will be replaced by “Page1″ found in the host template.

However, if your master pages are embedded in your fragments, then you don’t want to share page definitions. In this case there is less ambiguity if we use ID references instead of name references.

In fact, there is a bug in the current shipping products where if the top-level “Page1″ is in use when group1 is added to the layout, then “Page1″ will continue to be used for “group1″ — but it is the wrong “Page1″.  Here is a sample XDP to illustrate the bug.  The workaround is to either use unique names for your nested master pages, or switch to use id references.

Using unique names is easier. Using id references means either hand-editing the XML source or writing a designer macro to change the syntax.