Documentation: SSI-Container Directive

Specification

Found within the BODY tag of an HTML document, any DIV tag(s) with this case-sensitive value for the TITLE attribute and a globally-unique and case-sensitive value for the ID attribute denotes a placeholder for content from other resource documents. These specially-marked DIVs may have content of their own that is treated as default content that will be part of the final merged document only if no other resource document in the current merge chain overrides it. A document may have any number of these containers in it, nested or otherwise.

Synopsis

<div
   title="SSI-Container"
   id="GLOBALLY_UNIQUE_IDENTIFIER"
>
   DEFAULT_CONTENT
</div>
GLOBALLY_UNIQUE_IDENTIFIER
This must be a valid HTML ID Attribute Value . This ID attribute value sets the exact identifier that other SSI-Filler DIV directives must precisely match in order to replace its content during a merge. This value is deliberately case-sensitive to HTML Master Pages and an error message will be generated if this ID value is identical to the ID of any other SSI-Container that exists in the same Master Page.
DEFAULT_CONTENT
This can be absolutely nothing; any SSI-Container DIV tag may be empty to provide no default content. If you provide valid HTML content here, that content will be expressed in the final merged document if no properly mated SSI-Filler has replaced it.

Samples

The following are all functional examples of using this directive:

  1. A container with no default value; this container will simply be removed from the final merged document if no content is assigned to it from a child resource document:
    <div title="SSI-Container" id="unique-placeholder-id-1"></div>
  2. A container with a simple default value; this default value will be promoted to the container tag's level (wholly replacing the container itself) in the final merged document if no other content is assigned to it from a child resource document:
    <div title="SSI-Container" id="caseSensitiveId">
       Default Placeholder Content
    </div>
  3. The default content of a container can be as simple or as complex as you need for your Master Page template design; however, the final HTML that results from the merge should be valid within the final merged document (this advice is not enforced but is highly recommended):
    <div title="SSI-Container" id="globallyUniqueContainerID001">
       <h1>Default Placeholder Content</h1>
       <p>This can be any markup you want to be displayed in the
          final merged document when no other child document assigns
          content to this container!</p>
    </div>
  4. Multiple containers in the same Master Page template file are very useful as long as each container has a globally-unique ID value:
    <div title="SSI-Container" id="unique-id-1"></div>
    <div title="SSI-Container" id="unique-id-2">
       <div>Multiple Containers In The Same Document</div>
    </div>
  5. Nesting containers is possible but has limited use because any child resource document that assigns content to an outer container will destroy all containers within that outer container, so use this technique with caution:
    <div title="SSI-Container" id="globallyUniqueContainerID001">
       <h1>Containers Can Be Nested, With or Without Default Content</h1>
       <p>But be warned: if the outer container is overwritten
          because an included child assigns content to it, then this
          nested container will be lost, even if a child document
          assigns content to it.</p>
       <div title="SSI-Container" id="nestedGloballyUniqueID001">
          <p>Default Nested Placeholder Content</p>
       </div>
    </div>

Rules

Standard HTML attribute value rules apply except that the TITLE value, "SSI-Container", is case-sensitive to HTML Master Pages. Incorrectly capitalized values like "ssi-container" are ignored.

These containers may be placed in any document that is treated as a Master Page (in that it is called via an SSI-Template directive in a child resource document). These containers are ignored (and not removed) in any resource document that is directly accessed without being merged as a Master Page.

These containers may be empty or contain optional default content. Content that is assigned to replace these containers from child resource documents via matching SSI-Filler tags wholly overwrites all default content in these containers and is promoted to the level of the container itself (the SSI-Container DIV markup is removed from the final merged document). Because of this, be sure to never put critical content (that must always appear on final merged documents) within these containers and never style the SSI-Container DIVs themselves. If you need to style all content that targets a particular container, wrap the container itself in another DIV (or other appropriate element) and style that wrapper element, instead.

These containers may be nested. However, if any child document in the current merge chain targets a container that has one or more nested containers as children, all nested containers within the targeted container will be destroyed without any warning, including all of their content (default or anything already merged from a child document). Use container nesting in your Master Page template designs with caution.

Validation

These container DIV tags are valid HTML and will not interfere with W3C HTML Validators provided that you use valid ID attribute values and no other invalid markup. Note that these container DIV tags are removed from the final merged document (any content within them is promoted to the container's level) and, under normal circumstances, will not be presented to your end users.