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

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

    See source

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

  • children : Array.<(Template | Node)>

    The children of the template. They can be either:

    See source
    • independent instances of Template (sub–templates),
    • native DOM Nodes.

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

  • eventListeners : Object

    The DOM event listeners of the template.

    See source

  • tag : String

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

    See source

  • text : Array.<(String | TemplateValueSchema)>

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

    See source

  • _isRendered : Boolean

    protected readonly

    Indicates whether this particular Template instance has been rendered.

    See source

  • _revertData : RenderData

    protected readonly

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

    See source

    See: apply.

Methods

  • constructor( def )

    Creates an instance of the Template class.

    See source

    Parameters

    def : TemplateDefinition

    The definition of the template.

  • apply( node )

    Applies the template to an existing DOM Node, either HTML element or text.

    See source

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

    Root node for the template to apply.

    Related:

  • delegate( events ) → EmitterMixinDelegateChain

    mixed

    Delegates selected events to another Emitter. For instance:

    See source
    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 : String

    Event names that will be delegated to another emitter.

    Returns

    EmitterMixinDelegateChain

  • fire( eventOrInfo, [ args ] ) → *

    mixed

    Fires an event, executing all callbacks registered for it.

    See source

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

    Parameters

    eventOrInfo : String | EventInfo

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

    [ args ] : *

    Additional arguments to be passed to the callbacks.

    Returns

    *

    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() → Iterable.<View>

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

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

    Iterable.<View>

  • listenTo( emitter, event, callback, [ options ] = { [options.priority] } )

    mixed

    Registers a callback function to be executed when an event is fired in a specific (emitter) object.

    See source

    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.

    Parameters

    emitter : Emitter

    The object that fires the event.

    event : String

    The name of the event.

    callback : function

    The function to be called on event.

    [ options ] : Object

    Additional options.

    Properties
    [ options.priority ] : PriorityString | Number

    The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.

    Defaults to 'normal'

    Defaults to {}

  • off( event, callback )

    mixed

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

    See source

    Parameters

    event : String

    The name of the event.

    callback : function

    The function to stop being called.

  • on( event, callback, [ options ] = { [options.priority] } )

    mixed

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

    See source

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

    Parameters

    event : String

    The name of the event.

    callback : function

    The function to be called on event.

    [ options ] : Object

    Additional options.

    Properties
    [ options.priority ] : PriorityString | Number

    The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.

    Defaults to 'normal'

    Defaults to {}

  • once( event, callback, [ options ] = { [options.priority] } )

    mixed

    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

    Parameters

    event : String

    The name of the event.

    callback : function

    The function to be called on event.

    [ options ] : Object

    Additional options.

    Properties
    [ options.priority ] : PriorityString | Number

    The priority of this event callback. The higher the priority value the sooner the callback will be fired. Events having the same priority are called in the order they were added.

    Defaults to 'normal'

    Defaults to {}

  • render() → HTMLElement | Text

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

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

    See: apply.

    Returns

    HTMLElement | Text

  • revert( node )

    Reverts a template applied to a DOM node.

    See source

    Parameters

    node : Node

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

  • stopDelegating( [ event ], [ emitter ] )

    mixed

    Stops delegating events. It can be used at different levels:

    See source
    • 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.

  • stopListening( [ emitter ], [ event ], [ callback ] )

    mixed

    Stops listening for events. It can be used at different levels:

    See source
    • 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.

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

    protected

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

    See source

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

    Parameters

    options : Object

    Binding options.

    Properties
    options.schema : TemplateValueSchema
    options.updater : function

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

    options.data : RenderData

    Rendering data.

  • _renderAttributes( data )

    protected

    Renders HTML element attributes out of attributes.

    See source

    Parameters

    data : RenderData

    Rendering data.

  • _renderElement( data )

    protected

    Renders an HTML element out of the template.

    See source

    Parameters

    data : RenderData

    Rendering data.

  • _renderElementChildren( data )

    protected

    Recursively renders HTML element's children from children.

    See source

    Parameters

    data : RenderData

    Rendering data.

  • _renderNode( data )

    protected

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

    See source

    Parameters

    data : RenderData

    Rendering data.

  • _renderText( data )

    protected

    Renders a text node out of text.

    See source

    Parameters

    data : RenderData

    Rendering data.

  • _revertTemplateFromNode( node, revertData )

    protected

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

    See source

    Parameters

    node : HTMLElement | Text

    A node to be reverted.

    revertData : Object

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

  • _setUpListeners( data )

    protected

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

    See source

    Parameters

    data : RenderData

    Rendering data.

  • _renderStyleAttribute( styles, data )

    private

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

    See source

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

    Styles located in attributes.style of TemplateDefinition.

    data : RenderData

    Rendering data.

Static methods

  • bind( observable, emitter ) → BindChain

    static

    An entry point to the interface which binds DOM nodes to observables. There are two types of bindings:

    See source

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

    Parameters

    observable : Observable

    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

  • extend( template, def )

    static

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

    See source
    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 : TemplateDefinition

    Additional definition to be applied to a template.