CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

Template (ui)

@ckeditor/ckeditor5-ui/src/template

class
See source

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.

Filtering

Properties

  • attributes : Record<string, AttributeValues> | undefined

    See source

    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.

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

    See source

    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.

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

    See source

    The DOM event listeners of the template.

  • ns : string | undefined

    See source

  • tag : string | undefined

    See source

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

  • text : Array<TemplateSimpleValue | TemplateBinding> | undefined

    See source

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

  • private

    _isRendered : boolean

    See source

    Indicates whether this particular Template instance has been rendered.

  • private

    _revertData : null | RevertData

    See source

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

    See: apply.

Methods

  • constructor( def )

    See source

    Creates an instance of the Template class.

    Parameters

    def : TemplateDefinition

    The definition of the template.

  • apply( node ) → HTMLElement | Text

    See source

    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>'

    Parameters

    node : HTMLElement | Text

    Root node for the template to apply.

    Returns

    HTMLElement | Text

    Related:

  • inherited

    delegate( events ) → EmitterMixinDelegateChain

    See source

    Delegates selected events to another Emitter. For instance:

    emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );

    then eventX is delegated (fired by) emitterB and emitterC along with data:

    emitterA.fire( 'eventX', data );

    and eventY is delegated (fired by) emitterC along with data:

    emitterA.fire( 'eventY', data );

    Parameters

    events : Array<string>

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain

  • inherited

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

    See source

    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.

    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>>

    See source

    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 );
}

    Returns

    IterableIterator<View<HTMLElement>>

  • inherited

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

    See source

    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' );

    An event callback can stop the event and set the return value of the fire method.

    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

  • inherited

    off( event, callback ) → void

    See source

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

    Parameters

    event : string

    The name of the event.

    callback : Function

    The function to stop being called.

    Returns

    void

  • inherited

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

    See source

    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).

    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

  • inherited

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

    See source

    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.

    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

    See source

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

    const domNode = new Template( { ... } ).render();

    See: apply.

    Returns

    HTMLElement | Text

  • revert( node ) → void

    See source

    Reverts a template applied to a DOM node.

    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

  • inherited

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

    See source

    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.

    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

  • inherited

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

    See source

    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.

    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

  • private

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

    See source

    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.

    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

  • private

    _renderAttributes( data ) → void

    See source

    Renders HTML element attributes out of attributes.

    Parameters

    data : RenderData

    Rendering data.

    Returns

    void

  • private

    _renderElement( data ) → HTMLElement | Text

    See source

    Renders an HTML element out of the template.

    Parameters

    data : RenderData

    Rendering data.

    Returns

    HTMLElement | Text

  • private

    _renderElementChildren( data ) → void

    See source

    Recursively renders HTML element's children from children.

    Parameters

    data : RenderData

    Rendering data.

    Returns

    void

  • private

    _renderNode( data ) → HTMLElement | Text

    See source

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

    Parameters

    data : RenderData

    Rendering data.

    Returns

    HTMLElement | Text

  • private

    _renderStyleAttribute( styles, data ) → void

    See source

    Renders the style attribute of an HTML element based on attributes.

    A style attribute is an object with static values:

    attributes: {
	style: {
		color: 'red'
	}
}

    or values bound to Model properties:

    attributes: {
	style: {
		color: bind.to( ... )
	}
}

    Note: The style attribute is rendered without setting the namespace. It does not seem to be needed.

    Parameters

    styles : Record<string, TemplateSimpleValue | TemplateBinding>

    Styles located in attributes.style of TemplateDefinition.

    data : RenderData

    Rendering data.

    Returns

    void

  • private

    _renderText( data ) → HTMLElement | Text

    See source

    Renders a text node out of text.

    Parameters

    data : RenderData

    Rendering data.

    Returns

    HTMLElement | Text

  • private

    _revertTemplateFromNode( node, revertData ) → void

    See source

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

    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

  • private

    _setUpListeners( data ) → void

    See source

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

    Parameters

    data : RenderData

    Rendering data.

    Returns

    void

Static methods

  • static

    bind( observable, emitter ) → BindChain<TObservable>

    See source

    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();
    • 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();

    Also see bindTemplate.

    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>

  • static

    extend( template, def ) → void

    See source

    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>

    Parameters

    template : Template

    An existing template instance to be extended.

    def : Partial<TemplateDefinition>

    Additional definition to be applied to a template.

    Returns

    void