...and Filling Them

When using this HTML Master Pages solution, a "resource document" is any whole, standards-compliant HTML document (with a small caveat that is discussed elsewhere) that is marked up to merge with a Master Page. The exhaustive details of how a resource document's HEAD content is merged with that of its Master Page is covered in the Merging HEADs section. For this discussion about how to set up BODY content merging, we will lightly cover the interplay between all three of the HTML Master Pages directives. A more detailed, line-by-line analysis of the merging process is explored in the Walk-Through.

Once you have created a Master Page with SSI-Container DIVs, creating resource documents for it -- or even other subordinate Master Pages -- is as simple as filling-in-the-blanks. To the resource document, just add an appropriate SSI-Template META directive to its HEAD and exactly one SSI-Filler DIV to its BODY for each SSI-Container DIV in the Master Page that you want to replace with content from the resource document. Any default content in SSI-Container DIVs that you choose not to overwrite from your resource document (or subordinate Master Page) will appear in the final merged document.

It is important to understand that the Master Page during a particular merge is the authority on BODY content. The BODY content of resource documents will be discarded if not specifically marked to be merged with the Master Page's containers, as we will illustrate here. Stated another way, anything in the BODY of the resource document that is not wrapped in an SSI-Filler DIV with an ID attribute value that precisely matches the ID attribute value of an SSI-Container DIV in the immediate Master Page will be discarded.

Note that a resource document must always contain an SSI-Template META directive and it should contain at least one SSI-Filler DIV. Without an SSI-Template META directive, HTML Master Pages won't merge your document because it won't know what Master Page to merge it with. And without at least one SSI-Filler DIV, HTML Master Pages will discard the entire BODY of the resource document, merging only the HEAD contents with the indicated Master Page template.

Examples

With all those warnings and caveats covered, let's finally take a look at what a resource document looks like under several supported scenarios:

Single container content replacement

<!DOCTYPE html>
<html>
   <head>
      <title>Sample Resource Document</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <meta name="SSI-Template" content="/myMasterPage.html">
   </head>
   <body>
      <div title="SSI-Filler" id="unique-id-001">
         <p>This content will appear in the final merged document,
            fully overwriting any default content that may exist in the
            matching SSI-Container (with id="unique-id-001") within the
            /myMasterPage.html file.</p>
      </div>
   </body>
</html>

Single container with "designer content" that will be discarded during a merge

<!DOCTYPE html>
<html>
   <head>
      <title>Sample Resource Document</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <meta name="SSI-Template" content="/myMasterPage.html">
   </head>
   <body>
      <h1>Designer Content</h1>
      <p>Anything not wrapped with an SSI-Filler DIV will be
         discarded during a merge. You can exploit this if you need
         to preview your page without a merge, on purpose, by
         deliberately "breaking" the SSI-Template META directive in
         this document. While doing so has limited value, it may be
         useful for design-time tests and other experimentation
         without incurring the additional HEAD and BODY content that
         will be added to the resource document when a merge occurs.
         Such a testing scenario can be useful should you ever
         encounter any troublesome side-effects that your Master
         Pages impose on your carefully-crafted resource documents.</p>
      <h1>Actual Content</h1>
      <div title="SSI-Filler" id="unique-id-001">
         <p>This content will appear in the final merged document,
            fully overwriting any default content that may exist in the
            matching SSI-Container (with id="unique-id-001") within the
            /myMasterPage.html file.</p>
      </div>
   </body>
</html>

Multiple simultaneous container content replacements

<!DOCTYPE html>
<html>
   <head>
      <title>Sample Resource Document</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <meta name="SSI-Template" content="/myMasterPage.html">
   </head>
   <body>
      <div title="SSI-Filler" id="unique-id-001">
         <p>This content will appear in the final merged document,
            fully overwriting any default content that may exist in the
            matching SSI-Container (with id="unique-id-001") within the
            /myMasterPage.html file.</p>
      </div>
      <div title="SSI-Filler" id="unique-id-002">
         <p>With unique ID attribute values that are properly
            matched, you are able to create and fill any number of
            containers during each merge.</p>
      </div>
   </body>
</html>

A chained Master Page is just another resource document that happens to have all three HTML Master Pages directives at once. This enables it to contribute some HEAD and BODY content to its immediate Master Page while accepting other content from its own resource documents. You must remember that anything in its BODY that isn't also wrapped with a properly matched SSI-Filler DIV will be discarded, so in chained Master Pages, always wrap your SSI-Container DIVs in SSI-Filler DIVs when your Master Page chains into another Master Page, as illustrated here:

<!DOCTYPE html>
<html>
   <head>
      <title>Sample Resource Document</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <meta name="SSI-Template" content="/myOtherMasterPage.html">
   </head>
   <body>
      <div title="SSI-Filler" id="unique-id-001">
         <h1>Container With Default Content</h1>
         <p>This content will appear in the final merged document,
            in addition to anything other resource documents add to
            this container:.</p>
         <div title="SSI-Container" id="chained-id-A">
            <p>Default content in chained containers like this is
               also supported.</p>
            <p>In case it isn't obvious, resource document that
               target this chained Master Page must use
               id="chained-id-A" in their SSI-Filler DIVs to be merged
               with this SSI-Container and they cannot target
               id="unique-id-001" because in this Master Page,
               unique-id-001 is a filler ID, not a container.</p>
         </div>
      </div>
   </body>
</html>