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 or an HTML tag name).

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: (component class constructor)|HTMLTemplateElement|stringthe descriptor that will be used to create the element

Returns: Element the new element

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.

See also html, a helper which returns a similar result but as an DocumentFragment.

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: Nodean 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 with a new element, 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: Elementthe node to replace
  • descriptor: (component class constructor)|HTMLTemplateElement|stringthe descriptor used to generate the replacement element

Returns: Element the replacement node(s)