Documentation: Home Page Resource

Home Is Where The Content Is

A web-site's "home page" is like any other resource document. The difference with HTML Master Pages is that you need to wrap the content of your home page in a specially-identified SSI-Filler DIV tag so that it can be merged with your site-level Master Page, which you must also "point to" using an SSI-Template META directive. Sound complicated? Don't worry; it really is simple.

For this illustration of a simple merge, we will use the following resource document file (our fictitious web-site's home page):

/index.html
<!DOCTYPE html>
<html>
   <head>
      <title>Resource Document</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <meta name="SSI-Template" content="site-master.html">
      <meta name="description" content="Specific description of this page">
      <meta name="keywords" content="PAGE,SPECIFIC,KEYWORDS,HERE">
      <style>
         article {
            color: red;
         }
         article h1 {
            text-align: center;
            font-size: 1em;
         }
      </style>
   </head>
   <body>
      <div title="SSI-Filler" id="master-content-1">
         <h1>Resource Document</h1>
         <p>With a simple ID match between an SSI-Filler content DIV and
            an SSI-Container placeholder DIV, merging is easy!</p>
      </div>
      <p>This paragraph will be discarded because it does not map to any
         container in the immediate Master Page.</p>
   </body>
</html>

Results

When we open a web browser and point it at http://your-site/index.html, the output should be much more interesting than the Master Page alone:

Figure 3: Rendered Resource Document When Merged

The source code of the final merged document readily illustrates that the HEAD and BODY tags of the resource document and its Master Page have been merged as expected:

<!DOCTYPE html>
<html>
   <head>
      <title>Resource Document - Your Site</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <meta name="description" content="Specific description of this page">
      <link rel="stylesheet" href="style-master.css">
      <meta name="keywords" content="PAGE,SPECIFIC,KEYWORDS,HERE">
      <style>
         article {
            color: red;
         }
         article h1 {
            text-align: center;
            font-size: 1em;
         }
      </style>
   </head>
   <body>
      <header>
         <h1>On Every Page</h1>
         <p>This content will appear on every page that points to this
            file as its Master Page.</p>
      </header>
      <article>
         <h1>Resource Document</h1>
         <p>With a simple ID match between an SSI-Filler content DIV and
            an SSI-Container placeholder DIV, merging is easy!</p>
      </article>
      <footer>
         &copy; Your copyright notice here
         <address>
            Your name,<br>
            when this page was last updated, and<br>
            how to contact you here.
         </address>
      </footer>
   </body>
</html>
Figure 4: Resulting HTML, Resource Document Merged with Master Page

Analysis

You should notice all of the following occurred during the merge:

  1. the TITLE tag was updated to reflect the relationship between the resource document and its Master Page;
  2. shared HEAD tags and elements in the resource document overwrote those of the Master Page, specifically notice that the description META tag became that set by the resource document;
  3. unique HEAD tags and elements in the Master Page's HEAD tag were left intact, specifically notice the style-sheet LINK from the Master Page;
  4. unique HEAD tags and elements in the resource document were appended to the end of the Master Page's HEAD tag, specifically notice the keywords META and the in-page STYLE tag were imported this way;
  5. the SSI-Template directive was stripped out;
  6. all SSI-Container directives in the BODY tag of the Master Page have been removed from the final merged document and replaced by the resource document's content that was wrapped in SSI-Filler directives that had an identical ID; and
  7. any BODY content of the resource document that wasn't wrapped in a properly mated SSI-Filler directive was discarded.

Un-Merged Result

For contrast, the following shows what the resource document would look like if it weren't merged by HTML Master Pages. This outcome was accomplished by intentionally misspelling the NAME attribute value of the SSI-Template directive in the resource document:

Figure 5: Rendered Resource Document Without Merging

Of course, the resulting source code is identical to that of the resource document illustrated in Figure 4 except for the intentionally misspelled SSI-Template directive's NAME attribute value:

<!DOCTYPE html>
<html>
   <head>
      <title>Resource Document</title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
      <meta name="ssiTemplate" content="site-master.html">
      <meta name="description" content="Specific description of this page">
      <meta name="keywords" content="PAGE,SPECIFIC,KEYWORDS,HERE">
      <style>
         article {
            color: red;
         }
         article h1 {
            text-align: center;
            font-size: 1em;
         }
      </style>
   </head>
   <body>
      <div title="SSI-Filler" id="master-content-1">
         <h1>Resource Document</h1>
         <p>With a simple ID match between an SSI-Filler content DIV and
            an SSI-Container placeholder DIV, merging is easy!</p>
      </div>
      <p>This paragraph will be discarded because it does not map to any
         container in the immediate Master Page.</p>
   </body>
</html>
Figure 6: Resulting HTML, Intentionally Broken Resource Document

You should notice that the SSI-Filler directive is left unprocessed and the broken SSI-Template directive is left as-is. Without a properly constructed SSI-Template directive in this broken resource document, the merging algorithm from HTML Master Pages is simply never triggered.