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

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',
		'--color': 'red'
	}
}
```
Copy code
or values bound to UIModel properties:
```
attributes: {
	style: {
		color: bind.to( ... ),
		'--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
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 iconprivate

_revertData : null | RevertData Lock iconprivate

Methods

constructor( def )

Parameters

apply( node ) → HTMLElement | Text

Parameters

Returns

Related:

delegate( events ) → EmitterMixinDelegateChaininherited

Parameters

Returns

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

Type parameters

Parameters

Returns

getViews() → IterableIterator<View<HTMLElement>>

Returns

listenTo( emitter, event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

off( event, callback ) → voidinherited

Parameters

Returns

on( event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

once( event, callback, [ options ] ) → voidinherited

Type parameters

Parameters

Returns

render() → HTMLElement | Text

Returns

revert( node ) → void

Parameters

Returns

stopDelegating( [ event ], [ emitter ] ) → voidinherited

Parameters

Returns

stopListening( [ emitter ], [ event ], [ callback ] ) → voidinherited

Parameters

Returns

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

Parameters

Returns

_renderAttributes( data ) → void Lock iconprivate

Parameters

Returns

_renderElement( data ) → HTMLElement | Text Lock iconprivate

Parameters

Returns

_renderElementChildren( data ) → void Lock iconprivate

Parameters

Returns

_renderNode( data ) → HTMLElement | Text Lock iconprivate

Parameters

Returns

_renderStyleAttribute( styles, data ) → void Lock iconprivate

Parameters

Returns

_renderText( data ) → HTMLElement | Text Lock iconprivate

Parameters

Returns

_revertTemplateFromNode( node, revertData ) → void Lock iconprivate

Parameters

Returns

_setUpListeners( data ) → void Lock iconprivate

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