template

Helpers for dynamically creating and patching component templates

Overview

The ShadowTemplateMixin lets you define a component template that will be used to popuplate the shadow subtree of new component instances. These helpers, especially the html function, are intended to simplify the creation of such templates.

In particular, these helpers can be useful in patching templates inherited from a base class.

Some of these functions take descriptors that can either be a class, a tag name, or an HTML template. These are generally used to fill specific roles in an element's template; see element roles.

API

createElement(descriptor) static method

Create an element from a role descriptor (a component class constructor, an HTML tag name, or an HTML template).

If the descriptor is an HTML template, and the resulting document fragment contains a single top-level node, that node is returned directly (instead of the fragment).

Parameters:

  • descriptor: function|string|HTMLTemplateElementthe descriptor that will be used to create the element

Returns: Node the new element

defaultSlot(tree) static method

Search a tree for a default slot: a slot with no "name" attribute. Return null if not found.

Parameters:

  • tree: DocumentFragmentthe tree to search

Returns: Nodenull

html(strings, substitutions) static method

A JavaScript template string literal that returns an HTML template.

Example:

const myTemplate = html`Hello, <em>world</em>.`

returns an HTMLTemplateElement whose innerHTML is Hello, <em>world</em>.

This function is called html so that it can be easily used with HTML syntax-highlighting extensions for various popular code editors.

Parameters:

  • strings: TemplateStringsArraythe strings passed to the JavaScript template literal
  • substitutions: Array.the variable values passed to the JavaScript template literal

Returns: HTMLTemplateElement

replace(original, replacement) static method

Replace an original node in a tree or document fragment with the indicated replacement node. The attributes, classes, styles, and child nodes of the original node will be moved to the replacement.

Parameters:

  • original: Node|nullan existing node to be replaced
  • replacement: Nodethe node to replace the existing node with

Returns: Node the updated replacement node

transmute(original, descriptor) static method

Replace a node or nodes with new element(s), transferring all attributes, classes, styles, and child nodes from the original(s) to the replacement(s).

The descriptor used for the replacements can be a 1) component class constructor, 2) an HTML tag name, or 3) an HTML template. For #1 and #2, if the existing elements that match the selector are already of the desired class/tag name, the replacement operation is skipped.

Parameters:

  • original: Array|NodeList|Nodethe node to replace
  • descriptor: function|string|HTMLTemplateElementthe descriptor used to generate replacement elements

Returns: ArrayNode the replacement node(s)

wrap(original, wrapper, destination) static method

Destructively wrap a node or document fragment with the indicated wrapper node. The contents of the original node/fragment are moved to the indicated destination node (which should be a node within the wrapper).

Parameters:

  • original: Nodethe node to wrap
  • wrapper: DocumentFragment|Elementthe node to wrap with
  • destination: stringa CSS selector indicated a node in the wrapper in which the original node should be put