HTML Templates

This Version
http://dvcs.w3.org/hg/webcomponents/raw-file/tip/spec/templates/index.html
Revision history
http://dvcs.w3.org/hg/webcomponents/log/tip/spec/templates/index.html
Participate
Discuss on public-webaps@w3.org (Web Applications Working Group)
File bugs (w3.org's Bugzilla)
Status
Living Draft
Editor
Dimitri Glazkov, Google, <>
Rafael Weinstein, Google, <>

Table of Contents

  1. Abstract
  2. About this Document
  3. Dependencies
  4. Terminology
  5. Elements and DOM Objects
  6. Acknowledgements

Abstract

This specification describes a method for declaring inert DOM subtrees in HTML and manipulating them to instantiate document fragments with identical contents.

About this Document

All diagrams, examples, notes, are non-normative, as well as sections explicitly marked as non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification.

To help with layering and to avoid circular dependencies between various parts of specification, this document consists of three consecutive narratives:

  1. setting up the stage for the specification,
  2. explaining of the conceptual model and algorithms behind it, and
  3. expressing this model with DOM interfaces and HTML elements.

In a sense, these parts can be viewed as math, which sets up the reasoning environment, physics, which is the theoretical reasoning about the concept, and mechanics, which is the is the practical application of this reasoning.

Any point, at which a conforming UA must make decisions about the state or reaction to the state of the conceptual model, is captured as algorithm. The algorithms are defined in terms of processing equivalence. The processing equivalence is a constraint imposed on the algorithm implementors, requiring the output of the both UA-implemented and the specified algorithm to be exactly the same for all inputs.

Dependencies

This document relies on the following specifications:

Terminology

The following terms are used throughout the specification:

Populate terminology section

DOM
The document object model
document
The Document Object Model's underlying document
node
Any DOM object that participates in a tree
element
A DOM object that implements the Element interface
DOM tree
Any tree, composed of DOM objects
DOM structure
A DOM tree or fragment of a DOM tree

Define template

Define template contents

Parsing HTML Templates

The parsing of the HTML Templates is defined as a set of additions to the HTML parsing algorithm:

Addition to "in body" insertion mode

Just before the Any other start tag rule in the "in body" insertion mode, add the following rule:

A start tag whose tag name is "template"
Run these steps:
  1. Reconstruct the active formatting elements, if any.
  2. Create an HTML element for the token.
  3. Append this element to the current node.
  4. Create a new Document node that does not have a browsing context and mark it as being an HTML document.
  5. With that Document, create a new DocumentFragment object.
  6. Set the DocumentFragment as template contents of the created element.
  7. Push this DocumentFragment onto the stack of open elements so that it is the new current node.
  8. Switch the insertion mode to "template contents".

Addition to the "in table" insertion mode

Just before the Anything else rule in the "in table" insertion mode, add the following rule:

A start tag whose tag name is "template"
Process the token using rules for the "in body" insertion mode.

Addition to the "in select" insertion mode

Just before the Anything else rule in the "in select" insertion mode, add the following rule:

A start tag whose tag name is "template"
Process the token using rules for the "in body" insertion mode.

"Template contents" insertion mode

When the user is to apply the rules for the "template contents" insertion mode, the user agent must handle the token as follows:

A character token that is one of U+0009 CHARACTER TABULATION, U+000A LINE FEED (LF), U+000C FORM FEED (FF), U+000D CARRIAGE RETURN (CR), or U+0020 SPACE
Insert the character into the current node.
A comment token
Append a Comment node to the current node with the data attribute set to the data given in the comment token.
A start tag whose name is one of: "caption", "col", "colgroup", "tbody", "td", "tfoot", "th", "thead", "tr"
Switch the insertion mode to "in table" and reprocess the current token.
Anything else
Switch the insertion mode to "in body" and reprocess the current token.

Elements and DOM Objects

The template element

The template template element represents a template.

Context
Where flow content is expected
Content Model
Metadata content
Children
Anything as template contents
Content attributes
Global attributes
DOM Interface

interface HTMLTemplateElement : HTMLElement {
    readonly attribute DocumentFragment content;
}
        
Attributes
content of type DocumentFragment, read-only
Provides access to template contents

Acknowledgements

Populate acknowledgments section