Template

class

A basic Template class. It renders a DOM HTML element or text from a definition and supports element attributes, children, bindings to observables and DOM event propagation.

A simple template can look like this:

const bind = Template.bind( observable, emitter );

new Template( {
	tag: 'p',
	attributes: {
		class: 'foo',
		style: {
			backgroundColor: 'yellow'
		}
	},
	on: {
		click: bind.to( 'clicked' )
	},
	children: [
		'A paragraph.'
	]
} ).render();

and it will render the following HTML element:

<p class="foo" style="background-color: yellow;">A paragraph.</p>

Additionally, the observable will always fire clicked upon clicking <p> in the DOM.

See TemplateDefinition to know more about templates and complex template definitions.

See source

Properties

attributes : Record<string, AttributeValues> | undefined

The attributes of the template, e.g. { id: [ 'ck-id' ] }, corresponding with the attributes of an HTML element.

Note: This property only makes sense when tag is defined.

See source (with github icon)
children : Array<Node | View<HTMLElement> | Template | ViewCollection<View<HTMLElement>>> | undefined

module:ui/template~Template#children
The children of the template. They can be either:
- independent instances of Template (sub–templates),
- native DOM Nodes.
Note: This property only makes sense when tag is defined.

See source (with github icon)
eventListeners : Record<string, Array<TemplateToBinding>> | undefined

The DOM event listeners of the template.

See source (with github icon)
ns : string | undefined

See source (with github icon)
tag : string | undefined

The tag (tagName) of this template, e.g. div. It also indicates that the template renders to an HTML element.

See source (with github icon)
text : Array<TemplateSimpleValue | TemplateBinding> | undefined

The text of the template. It also indicates that the template renders to a DOM text node.

See source (with github icon)
_isRendered : boolean
private

Indicates whether this particular Template instance has been rendered.

See source (with github icon)
_revertData : null | RevertData
private

The data used by the revert method to restore a node to its original state.

See: apply.

See source (with github icon)

Methods

constructor( def )

Creates an instance of the Template class.

See source (with github icon)

Parameters

def : TemplateDefinition

The definition of the template.
apply( node ) → HTMLElement | Text

module:ui/template~Template#apply
Applies the template to an existing DOM Node, either HTML element or text.

Note: No new DOM nodes will be created. Applying extends:

attributes, event listeners, and textContent of children only.

Note: Existing class and style attributes are extended when a template is applied to an HTML element, while other attributes and textContent are overridden.

Note: The process of applying a template can be easily reverted using the revert method.
```
const element = document.createElement( 'div' );
const observable = new Model( { divClass: 'my-div' } );
const emitter = Object.create( EmitterMixin );
const bind = Template.bind( observable, emitter );

new Template( {
	attributes: {
		id: 'first-div',
		class: bind.to( 'divClass' )
	},
	on: {
		click: bind( 'elementClicked' ) // Will be fired by the observable.
	},
	children: [
		'Div text.'
	]
} ).apply( element );

console.log( element.outerHTML ); // -> '<div id="first-div" class="my-div"></div>'
```
Copy code
See source (with github icon)

Parameters

node : HTMLElement | Text

Root node for the template to apply.

Returns

HTMLElement | Text

Related:
- Template#render
- Template#revert
delegate( events ) → EmitterMixinDelegateChain
inherited

module:ui/template~Template#delegate
Delegates selected events to another Emitter. For instance:
```
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
```
Copy code
then eventX is delegated (fired by) emitterB and emitterC along with data:
```
emitterA.fire( 'eventX', data );
```
Copy code
and eventY is delegated (fired by) emitterC along with data:
```
emitterA.fire( 'eventY', data );
```
Copy code
See source (with github icon)

Parameters

events : Array<string>

Event names that will be delegated to another emitter.

Returns

EmitterMixinDelegateChain
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]
inherited

Fires an event, executing all callbacks registered for it.

The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

See source (with github icon)

Type parameters

TEvent : extends BaseEvent

The type describing the event. See BaseEvent.

Parameters

eventOrInfo : GetNameOrEventInfo<TEvent>

The name of the event or EventInfo object if event is delegated.

args : TEvent[ 'args' ]

Additional arguments to be passed to the callbacks.

Returns

GetEventInfo<TEvent>[ 'return' ]

By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

`getViews() → IterableIterator<View<HTMLElement>>`

module:ui/template~Template#getViews

Returns an iterator which traverses the template in search of View instances and returns them one by one.

const viewFoo = new View();
const viewBar = new View();
const viewBaz = new View();
const template = new Template( {
	tag: 'div',
	children: [
		viewFoo,
		{
			tag: 'div',
			children: [
				viewBar
			]
		},
		viewBaz
	]
} );

// Logs: viewFoo, viewBar, viewBaz
for ( const view of template.getViews() ) {
	console.log( view );
}

See source

Returns

IterableIterator<View<HTMLElement>>

listenTo( emitter, event, callback, [ options ] ) → void
inherited

module:ui/template~Template#listenTo:BASE_EMITTER
Registers a callback function to be executed when an event is fired in a specific (emitter) object.

Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.
```
// myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
myEmitter.on( 'myGroup', genericCallback );
myEmitter.on( 'myGroup:myEvent', specificCallback );

// genericCallback is fired.
myEmitter.fire( 'myGroup' );
// both genericCallback and specificCallback are fired.
myEmitter.fire( 'myGroup:myEvent' );
// genericCallback is fired even though there are no callbacks for "foo".
myEmitter.fire( 'myGroup:foo' );
```
Copy code
An event callback can stop the event and set the return value of the fire method.

See source (with github icon)

Type parameters

TEvent : extends BaseEvent

The type describing the event. See BaseEvent.

Parameters

emitter : Emitter

The object that fires the event.

event : TEvent[ 'name' ]

The name of the event.

callback : GetCallback<TEvent>

The function to be called on event.

[ options ] : GetCallbackOptions<TEvent>

Additional options.

Returns

void
off( event, callback ) → void
inherited

Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

See source (with github icon)

Parameters

event : string

The name of the event.

callback : Function

The function to stop being called.

Returns

void
on( event, callback, [ options ] ) → void
inherited

Registers a callback function to be executed when an event is fired.

Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

See source (with github icon)

Type parameters

TEvent : extends BaseEvent

The type descibing the event. See BaseEvent.

Parameters

event : TEvent[ 'name' ]

The name of the event.

callback : GetCallback<TEvent>

The function to be called on event.

[ options ] : GetCallbackOptions<TEvent>

Additional options.

Returns

void
once( event, callback, [ options ] ) → void
inherited

Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

See source (with github icon)

Type parameters

TEvent : extends BaseEvent

The type descibing the event. See BaseEvent.

Parameters

event : TEvent[ 'name' ]

The name of the event.

callback : GetCallback<TEvent>

The function to be called on event.

[ options ] : GetCallbackOptions<TEvent>

Additional options.

Returns

void
render() → HTMLElement | Text

module:ui/template~Template#render
Renders a DOM Node (an HTML element or text) out of the template.
```
const domNode = new Template( { ... } ).render();
```
Copy code
See: apply.

See source (with github icon)

Returns

HTMLElement | Text
revert( node ) → void

Reverts a template applied to a DOM node.

See source (with github icon)

Parameters

node : HTMLElement | Text

The root node for the template to revert. In most of the cases, it is the same node used by apply.

Returns

void
stopDelegating( [ event ], [ emitter ] ) → void
inherited

module:ui/template~Template#stopDelegating
Stops delegating events. It can be used at different levels:
- To stop delegating all events.
- To stop delegating a specific event to all emitters.
- To stop delegating a specific event to a specific emitter.
See source (with github icon)

Parameters

[ event ] : string

The name of the event to stop delegating. If omitted, stops it all delegations.

[ emitter ] : Emitter

(requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.

Returns

void
stopListening( [ emitter ], [ event ], [ callback ] ) → void
inherited

module:ui/template~Template#stopListening:BASE_STOP
Stops listening for events. It can be used at different levels:
- To stop listening to a specific callback.
- To stop listening to a specific event.
- To stop listening to all events fired by a specific object.
- To stop listening to all events fired by all objects.
See source (with github icon)

Parameters

[ emitter ] : Emitter

The object to stop listening to. If omitted, stops it for all objects.

[ event ] : string

(Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

[ callback ] : Function

(Requires the event) The function to be removed from the call list for the given event.

Returns

void
_bindToObservable( options = { options.data, options.schema, options.updater } ) → void
private

For a given TemplateValueSchema containing TemplateBinding activates the binding and sets its initial value.

Note: TemplateValueSchema can be for HTML element attributes or text node textContent.

See source (with github icon)

Parameters

options : object

Binding options.

Properties

options.data : RenderData

Rendering data.

options.schema : Array<TemplateSimpleValue | TemplateBinding>

options.updater : Updater

A function which updates the DOM (like attribute or text).

Returns

void
_renderAttributes( data ) → void
private

Renders HTML element attributes out of attributes.

See source (with github icon)

Parameters

data : RenderData

Rendering data.

Returns

void
_renderElement( data ) → HTMLElement | Text
private

Renders an HTML element out of the template.

See source (with github icon)

Parameters

data : RenderData

Rendering data.

Returns

HTMLElement | Text
_renderElementChildren( data ) → void
private

Recursively renders HTML element's children from children.

See source (with github icon)

Parameters

data : RenderData

Rendering data.

Returns

void
_renderNode( data ) → HTMLElement | Text
private

Renders a DOM Node (either an HTML element or text) out of the template.

See source (with github icon)

Parameters

data : RenderData

Rendering data.

Returns

HTMLElement | Text
_renderStyleAttribute( styles, data ) → void
private

module:ui/template~Template#_renderStyleAttribute
Renders the style attribute of an HTML element based on attributes.

A style attribute is an object with static values:
```
attributes: {
	style: {
		color: 'red'
	}
}
```
Copy code
or values bound to UIModel properties:
```
attributes: {
	style: {
		color: bind.to( ... )
	}
}
```
Copy code
Note: The style attribute is rendered without setting the namespace. It does not seem to be needed.

See source (with github icon)

Parameters

styles : Record<string, TemplateSimpleValue | TemplateBinding>

Styles located in attributes.style of TemplateDefinition.

data : RenderData

Rendering data.

Returns

void
_renderText( data ) → HTMLElement | Text
private

Renders a text node out of text.

See source (with github icon)

Parameters

data : RenderData

Rendering data.

Returns

HTMLElement | Text
_revertTemplateFromNode( node, revertData ) → void
private

Reverts template data from a node to return it to the original state.

See source (with github icon)

Parameters

node : HTMLElement | Text

A node to be reverted.

revertData : RevertData

An object that stores information about what changes have been made by apply to the node. See revertData for more information.

Returns

void
_setUpListeners( data ) → void
private

Activates on event listeners from the TemplateDefinition on an HTML element.

See source (with github icon)

Parameters

data : RenderData

Rendering data.

Returns

void

Static methods

bind( observable, emitter ) → BindChain<TObservable>
static

module:ui/template~Template.bind
An entry point to the interface which binds DOM nodes to observables. There are two types of bindings:
- HTML element attributes or text textContent synchronized with attributes of an Observable. Learn more about to and if.
```
const bind = Template.bind( observable, emitter );

new Template( {
	attributes: {
		// Binds the element "class" attribute to observable#classAttribute.
		class: bind.to( 'classAttribute' )
	}
} ).render();
```
Copy code
- DOM events fired on HTML element propagated through Observable. Learn more about to.
```
const bind = Template.bind( observable, emitter );

new Template( {
	on: {
		// Will be fired by the observable.
		click: bind( 'elementClicked' )
	}
} ).render();
```
Copy code
Also see bindTemplate.

See source (with github icon)

Type parameters

TObservable : extends Observable<TObservable>

Parameters

observable : TObservable

An observable which provides boundable attributes.

emitter : Emitter

An emitter that listens to observable attribute changes or DOM Events (depending on the kind of the binding). Usually, a View instance.

Returns

BindChain<TObservable>

`extend( template, def ) → void`
static

module:ui/template~Template.extend

Extends an existing Template instance with some additional content from another TemplateDefinition.

const bind = Template.bind( observable, emitter );

const template = new Template( {
	tag: 'p',
	attributes: {
		class: 'a',
		data-x: bind.to( 'foo' )
	},
	children: [
		{
			tag: 'span',
			attributes: {
				class: 'b'
			},
			children: [
				'Span'
			]
		}
	]
 } );

// Instance-level extension.
Template.extend( template, {
	attributes: {
		class: 'b',
		data-x: bind.to( 'bar' )
	},
	children: [
		{
			attributes: {
				class: 'c'
			}
		}
	]
} );

// Child extension.
Template.extend( template.children[ 0 ], {
	attributes: {
		class: 'd'
	}
} );

the outerHTML of template.render() is:

<p class="a b" data-x="{ observable.foo } { observable.bar }">
	<span class="b c d">Span</span>
</p>

See source

Parameters

template : Template: An existing template instance to be extended.
def : Partial<TemplateDefinition>: Additional definition to be applied to a template.

Returns

void

Template

Properties

attributes : Record<string, AttributeValues> | undefined

children : Array<Node | View<HTMLElement> | Template | ViewCollection<View<HTMLElement>>> | undefined

eventListeners : Record<string, Array<TemplateToBinding>> | undefined

ns : string | undefined

tag : string | undefined

text : Array<TemplateSimpleValue | TemplateBinding> | undefined

_isRendered : boolean Lock icon private

_revertData : null | RevertData Lock icon private

Methods

constructor( def )

Parameters

apply( node ) → HTMLElement | Text

Parameters

Returns

Related:

delegate( events ) → EmitterMixinDelegateChain inherited

Parameters

Returns

fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ] inherited

Type parameters

Parameters

Returns

getViews() → IterableIterator<View<HTMLElement>>

Returns

listenTo( emitter, event, callback, [ options ] ) → void inherited

Type parameters

Parameters

Returns

off( event, callback ) → void inherited

Parameters

Returns

on( event, callback, [ options ] ) → void inherited

Type parameters

Parameters

Returns

once( event, callback, [ options ] ) → void inherited

Type parameters

Parameters

Returns

render() → HTMLElement | Text

Returns

revert( node ) → void

Parameters

Returns

stopDelegating( [ event ], [ emitter ] ) → void inherited

Parameters

Returns

stopListening( [ emitter ], [ event ], [ callback ] ) → void inherited

Parameters

Returns

_bindToObservable( options = { options.data, options.schema, options.updater } ) → void Lock icon private

Parameters

Returns

_renderAttributes( data ) → void Lock icon private

Parameters

Returns

_renderElement( data ) → HTMLElement | Text Lock icon private

Parameters

Returns

_renderElementChildren( data ) → void Lock icon private

Parameters

Returns

_renderNode( data ) → HTMLElement | Text Lock icon private

Parameters

Returns

_renderStyleAttribute( styles, data ) → void Lock icon private

Parameters

Returns

_renderText( data ) → HTMLElement | Text Lock icon private

Parameters

Returns

_revertTemplateFromNode( node, revertData ) → void Lock icon private

Parameters

Returns

_setUpListeners( data ) → void Lock icon private

Parameters

Returns

Static methods

`attributes : Record<string, AttributeValues> | undefined`

`children : Array<Node | View<HTMLElement> | Template | ViewCollection<View<HTMLElement>>> | undefined`

`eventListeners : Record<string, Array<TemplateToBinding>> | undefined`

`ns : string | undefined`

`tag : string | undefined`

`text : Array<TemplateSimpleValue | TemplateBinding> | undefined`

`_isRendered : boolean`
private

`_revertData : null | RevertData`
private

`constructor( def )`

`apply( node ) → HTMLElement | Text`

`delegate( events ) → EmitterMixinDelegateChain`
inherited

`fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]`
inherited

`getViews() → IterableIterator<View<HTMLElement>>`

`listenTo( emitter, event, callback, [ options ] ) → void`
inherited

`off( event, callback ) → void`
inherited

`on( event, callback, [ options ] ) → void`
inherited

`once( event, callback, [ options ] ) → void`
inherited

`render() → HTMLElement | Text`

`revert( node ) → void`

`stopDelegating( [ event ], [ emitter ] ) → void`
inherited

`stopListening( [ emitter ], [ event ], [ callback ] ) → void`
inherited

`_bindToObservable( options = { options.data, options.schema, options.updater } ) → void`
private

`_renderAttributes( data ) → void`
private

`_renderElement( data ) → HTMLElement | Text`
private

`_renderElementChildren( data ) → void`
private

`_renderNode( data ) → HTMLElement | Text`
private

`_renderStyleAttribute( styles, data ) → void`
private

`_renderText( data ) → HTMLElement | Text`
private

`_revertTemplateFromNode( node, revertData ) → void`
private

`_setUpListeners( data ) → void`
private

`bind( observable, emitter ) → BindChain<TObservable>`
static

`extend( template, def ) → void`
static