Documentation: SSI-Template Directive

Specification

Found within the HEAD tag of an HTML document, a META element with this case-sensitive value for its NAME attribute is a directive to HTML Master Pages to retrieve the document specified in the CONTENT attribute and treat it as a Master Page that will receive content from the current resource document and any other resource documents that have already been merged into it (if this is a chained merge).

Synopsis

<meta
   name="SSI-Template"
   content="PATH_OR_URL"
>
PATH_OR_URL
This is either a file-path or a URL which points to this resource document's Master Page. A file-path may be set relative to the resource document or absolute based on the current web-site's root directory (not the web server's root directory). A URL must point to a document which the local web server is able to access.

Samples

The following are all functional examples of using this directive:

  1. Relative path pointing at a Master Page template in the same directory as the requested document:
    <meta name="SSI-Template" content="template.html">
  2. Relative path with directory traversal pointing at a Master Page template in the requested document's parent directory:
    <meta name="SSI-Template" content="../template.html">
  3. Absolute path pointing at a Master Page template in a specific directory under the current web-site's home:
    <meta name="SSI-Template" content="/path/to/master-template.html">
  4. URL-based path pointing at a hosted Master Page template on another web server:
    <meta name="SSI-Template" content="http://template-server/path/template.html">

Rules

The CONTENT value can be specified as:

For non-URL paths, the canonicalized path must reside within the current web-site's directory structure. Attempts to load files above the web-site root will be rejected by HTML Master Pages' own internal security check before any file access is attempted.

The specified file must exist, be readable by your web server, and have content, or HTML Master Pages will abort the merge request -- no matter how deeply chained or nested -- and produce an error message with the full requested path to facilitate troubleshooting.

Note that security settings on your web server may block HTML Master Pages from opening or reading the specified resource. This is especially true for Linux servers that have SELinux enabled and particularly affects URL-based resources. It is your responsibility to configure your own file permissions, firewall, and other security software (like SELinux) to permit requests that you intend to use.

Master Pages may become children of other Master Pages (creating a "chain" of Master Pages) by setting up an appropriate set of SSI-Template directives (one in each document that points to the "next" Master Page in the chain). Every chained merge combines each document pair in isolation (treating the merged result of what was once a Master Page and its child as a new child document of the next Master Page in the chain). Because of this isolated treatment, you must also chain SSI-Container + SSI-Filler content that you wish to propagate to the "next" Master Page.

Only one SSI-Template may be specified per document. If more than one is set, only the first such directive is utilized during a merge.

Validation

With a proprietary value for the NAME attribute of this META tag, an HTML document containing this HTML Master Pages directive during validation (say, by copying and pasting the raw HTML content of your document into a validator without first merging it) will not validate with the W3C HTML Validation engines unless the document is first merged with its Master Page. As with the other HTML Master Pages directives, HTML Master Pages strips this tag out of the final merged document. As long as all merged content is valid, the final merged document will validate.