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:

Additional Tokenization States

The additional tokenization states are similar to the RAWTEXT tokenization states in the parsing algorithm, but add an extra counter for allowing nested template elements with the goal of producing a character sequence between the two matching template tags in markup.

The nesting level counter indicates the current level of nested template elements. Its value must be set to 1 when first entering the template contents data state.

1. Template contents data state

Consume the next input character:

U+003C LESS-THAN SIGN (<)
Switch to the template contents less-than sign state.
U+0000 NULL
Parse error. Emit a U+FFFD REPLACEMENT CHARACTER character token.
EOF
Emit an end-of-file token.
Anything else
Emit the current input character as a character token.

2. Template contents less-than sign state

Consume the next input character:

U+002F SOLIDUS (/)
Set the temporary buffer to the empty string, then emit a U+002F SOLIDUS character token. Switch to the template contents end tag open state.
U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL LETTER Z
Set the temporary buffer to the empty string, then switch to the template contents tag name state. Reconsume current input character.
U+0061 LATIN SMALL LETTER A through to U+007A LATIN SMALL LETTER Z
Set the temporary buffer to the empty string, then switch to the template contents tag name state. Reconsume current input character.
Anything else
Switch to the template contents data state. Emit a U+003C LESS-THAN SIGN character token. Reconsume the current input character.

3. Template contents tag name state

Consume the next input character:

U+0009 CHARACTER TABULATION (tab)
U+000A LINE FEED (LF)
U+000C FORM FEED (FF)
U+0020 SPACE
Emit current input character as a character token. Switch to template contents before tag close state.
U+003E GREATER-THAN SIGN (>)
Switch to template contents before tag close state. Reconsume the current input character.
U+0000 NULL
Parse error. Append a U+FFFD REPLACEMENT CHARACTER character to the temporary buffer and emit it as a character token.
EOF
Emit an end-of-file token.
U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL LETTER Z
Append the lowercase version of the current input character to the temporary buffer and emit it as a character token.
Anything else
Append the current input character to the temporary buffer and emit it as a character token.

4. Template contents before tag close state

Consume the next input character:

U+003E GREATER-THAN SIGN (>)
If the temporary buffer is a string "template", then increment the nesting level counter. Emit the U+003E GREATER-THAN SIGN character token. Finally, switch to the template contents data state.
U+0000 NULL
Parse error. Emit a U+FFFD REPLACEMENT CHARACTER character token.
EOF
Emit an end-of-file token.
Anything else
Emit the current input character as a character token.

5. Template contents end tag open state

Consume the next input character:

U+0009 CHARACTER TABULATION (tab)
U+000A LINE FEED (LF)
U+000C FORM FEED (FF)
U+0020 SPACE
If the temporary buffer is a string "template", then decrement the nesting level counter. If after the decrement, the nesting level counter value is 0, create a new end tag token, set its name to the value of the temporary buffer, then switch to before attribute name state. Otherwise, emit a character token for each of the characters in the temporary buffer, then emit current input character as a character token. Switch to template contents before tag end close state.
U+003E GREATER-THAN SIGN (>)
If the temporary buffer is a string "template", then decrement the nesting level counter. If after the decrement, the nesting level counter value is 0, create a new end tag token, set its name to the value of the temporary buffer, then switch to data state. Emit the current tag token. Otherwise, switch to template contents before end tag close state and reconsume the current input character.
U+0000 NULL
Parse error. Append a U+FFFD REPLACEMENT CHARACTER character to the temporary buffer.
EOF
Emit a character token for each of the characters in the temporary buffer, then switch to the data state. Reconsume the EOF token.
U+0041 LATIN CAPITAL LETTER A through to U+005A LATIN CAPITAL LETTER Z
Append the lowercase version of the current input character to the temporary buffer.
Anything else
Append the current input character to the temporary buffer.

6. Template contents before end tag close state

Consume the next input character:

U+003E GREATER-THAN SIGN (>)
Emit the U+003E GREATER-THAN SIGN character token and witch to the template contents data state.
U+0000 NULL
Parse error. Emit a U+FFFD REPLACEMENT CHARACTER character token.
EOF
Emit an end-of-file token.
Anything else
Emit the current input character as a character 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