Template Reference

Related documents

• Template Markup Language (TML) Reference
• Character Entity Reference

Table of contents

• Introduction
• Constructor
• Instance methods
  • checkChildTags()
  • clone()
  • findChildrenByClassName()
  • getChildByTag()
  • getChildrenByTag()
  • splitChildrenByTag()
  • toString()
  • toText()
• Instance properties
  • children
  • props
  • tag

Introduction

The View uses templates to specify the visible elements. The View accepts Template objects, strings, numbers, or arrays of these.

Template objects capture an XML-like tree of elements. Each Template object has a tag that can be a standard HTML tag string, a published Component string, or a Component class. It also contains any attributes and children associated with each element. Unlike XML, children can be any JavaScipt type.

Template trees are normally built using Template Markup Language (TML).

Constructor

Syntax

new Template(tag, props, children)

Parameters

• tag (required)
  A string or a Component class (anything else fails an assertion). If a string, it may be either s standard HTML tag string or a published Component string. By convention, published component strings begin with a capital letter though there are exceptions.
• props (optional, default: {}).
  An object with string keys representing the node attributes.
• children (optional, default: [])
  An array of children. The array will be flattened and any string elements consisting only of whitespace will be removed. The acceptable types in the child array depend on the Component specified in the tag.

Instance methods

checkChildTags()

Syntax

checkChildTags(tagsAllowed, msg)

Check that the Template object's children array has valid children. Only Template children are examined; strings and numbers are ignored. The check is made with assert(), so a failure throws rather than returning.

Parameters

• tagsAllowed
  An array of allowed tags. Each tag string may have one of the following characters appended:

  • +
    The children must have one or more elements with this tag.
  • *
    The children must have zero or more elements with this tag.
  • ?
    The children must have zero or one element with this tag.
  • (no suffix)
    The children must have exactly one element with this tag.

  A child tag is accepted if it prefix-matches any entry in tagsAllowed (the test is s.match('^'+tag)), so an allowed tag that begins with a child's tag also admits that child.

• msg
  A message used as the prefix of the assertion failure message.

Return value

Nothing. The method only asserts; it fails an assertion if the children are not valid.

clone()

Syntax

clone()

Returns a new Template object identical to this one. Only the direct children of the template are copied.

Return value

A Template object.

findChildrenByClassName()

Syntax

findChildrenByClassName(className, …)

Searches the template tree from this Template object down, for children that have any of the classNames. Returns an array of children that have any of the specified classes.

Parameters

• className (all arguments)
  A CSS class string.

Return value

An array of Template objects representing any descendant of this Template object having any of the specified CSS classNames.

getChildByTag()

Syntax

getChildByTag(tag)

Return the first child that has the specified tag. Only the direct children of the Template object are searched.

Parameters

• tag
  A string or a Component class.

Return value

Return value A child Template that has a matching tag, or undefined if not found (the result of Array.find).

getChildrenByTag()

Syntax

getChildrenByTag(tag)

Return an array of children that have the specified tag. Only the direct children of this Template object are searched.

• tag
  A string or a Component class. Only a single tag is accepted.

Return value

An array of children that have the specified tag.

splitChildrenByTag()

Syntax

splitChildrenByTag(tag, ...)

Segregate child templates by tag. The arguments are a set of tags. It returns an array containing arrays. The outer array has an array element for each tag argument, plus one more for children not matching any tag argument. Children with matching tags are placed in the results array element corresponding to the tag position in the arguments. Strings, Numbers, and children that don't correspond to any category are placed in the last result array.

Parameters

• tag (all arguments)
  A string or a Component class.

Return value

An array of arrays.

toString()

Syntax

toString()

Convert this Template and its children into an XML string.

Note: this method is for Template objects only. To convert any TML result (Template objects, strings, or Numbers) to a string, use tml.toString(value); see tml.md.

Return value

An XML string.

toText()

Syntax

toText()

Convert this Template's children into a string containing only the text content.

Return value

A string.

Instance properties

children

The children array that was passed to the constructor, then flattened with blank strings filtered out. If no children were passed, then this is an empty array.

Value

An array containing Template objects and/or any JavaScipt type.

props

The props object that was passed to the constructor. If no props object was passed, then this is an empty object.

Value

An object.

tag

The tag string or Component class that was passed to the constructor.

Value

A String or Component class.