CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 4/API
Class

CKEDITOR.plugins.widget.repository

class
See source

Widget repository. It keeps track of all registered widget definitions and initialized instances. An instance of the repository is available under the CKEDITOR.editor.widgets property.

Filtering

Properties

Static properties

Methods

  • constructor( editor ) → repository

    See source

    Creates a widget repository instance. Note that the widget plugin automatically creates a repository instance which is available under the CKEDITOR.editor.widgets property.

    Parameters

    editor : editor

    The editor instance for which the repository will be created.

    Returns

    repository

  • add( name, widgetDef ) → definition

    See source

    Adds a widget definition to the repository. Fires the CKEDITOR.editor.widgetDefinition event which allows to modify the widget definition which is going to be registered.

    Parameters

    name : String

    The name of the widget definition.

    widgetDef : definition

    Widget definition.

    Returns

    definition

  • addUpcastCallback( callback )

    See source

    Adds a callback for element upcasting. Each callback will be executed for every element which is later tested by upcast methods. If a callback returns false, the element will not be upcasted.

    // Images with the "banner" class will not be upcasted (e.g. to the image widget).
editor.widgets.addUpcastCallback( function( element ) {
    if ( element.name == 'img' && element.hasClass( 'banner' ) )
        return false;
} );

    Parameters

    callback : Function

  • capture()

    See source

    Register event handler under the capturing stage on supported target.

  • checkSelection()

    See source

    Checks the selection to update widget states (selection and focus).

    This method is triggered by the checkSelection event.

  • checkWidgets( [ options ] )

    See source

    Checks if all widget instances are still present in the DOM. Destroys those instances that are not present. Reinitializes widgets on widget wrappers for which widget instances cannot be found. Takes nested widgets into account, too.

    This method triggers the checkWidgets event whose listeners can cancel the method's execution or modify its options.

    Parameters

    [ options ] : Object

    The options object.

  • define( name, meta )

    See source

    Predefine some intrinsic properties on a specific event name.

    Parameters

    name : String

    The event name

    meta : Object

  • del( widget )

    See source

    Removes the widget from the editor and moves the selection to the closest editable position if the widget was focused before.

    Parameters

    widget : widget

    The widget instance to be deleted.

  • destroy( widget, [ offline ] )

    See source

    Destroys the widget instance and all its nested widgets (widgets inside its nested editables).

    Parameters

    widget : widget

    The widget instance to be destroyed.

    [ offline ] : Boolean

    Whether the widget is offline (detached from the DOM tree) — in this case the DOM (attributes, classes, etc.) will not be cleaned up.

  • destroyAll( [ offline ], [ container ] )

    See source

    Destroys all widget instances.

    Parameters

    [ offline ] : Boolean

    Whether the widgets are offline (detached from the DOM tree) — in this case the DOM (attributes, classes, etc.) will not be cleaned up.

    [ container ] : element

    The container within widgets will be destroyed. This option will be ignored if the offline flag was set to true, because in such case it is not possible to find widgets within the passed block.

  • finalizeCreation( container )

    See source

    Finalizes a process of widget creation. This includes:

    This method is used by the default widget's command and is called after widget's dialog (if set) is closed. It may also be used in a customized process of widget creation and insertion.

    widget.once( 'edit', function() {
    // Finalize creation only of not ready widgets.
    if ( widget.isReady() )
        return;

    // Cancel edit event to prevent automatic widget insertion.
    evt.cancel();

    CustomDialog.open( widget.data, function saveCallback( savedData ) {
        // Cache the container, because widget may be destroyed while saving data,
        // if this process will require some deep transformations.
        var container = widget.wrapper.getParent();

        widget.setData( savedData );

        // Widget will be retrieved from container and inserted into editor.
        editor.widgets.finalizeCreation( container );
    } );
} );

    Parameters

    container : element | documentFragment

    The element or document fragment which contains widget wrapper. The container is used, so before finalizing creation the widget can be freely transformed (even destroyed and reinitialized).

  • fire( eventName, [ data ], [ editor ] ) → Boolean | Object

    See source

    Fires an specific event in the object. All registered listeners are called at this point.

    someObject.on( 'someEvent', function() { ... } );
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );             // Both listeners are called.

someObject.on( 'someEvent', function( event ) {
    alert( event.data );                    // 'Example'
} );
someObject.fire( 'someEvent', 'Example' );

    Parameters

    eventName : String

    The event name to fire.

    [ data ] : Object

    Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.

    [ editor ] : editor

    The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.

    Returns

    Boolean | Object

    A boolean indicating that the event is to be canceled, or data returned by one of the listeners.

  • fireOnce( eventName, [ data ], [ editor ] ) → Boolean | Object

    See source

    Fires an specific event in the object, releasing all listeners registered to that event. The same listeners are not called again on successive calls of it or of fire.

    someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );         // Above listener called.
someObject.fireOnce( 'someEvent' );     // Above listener called.
someObject.fire( 'someEvent' );         // No listeners called.

    Parameters

    eventName : String

    The event name to fire.

    [ data ] : Object

    Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.

    [ editor ] : editor

    The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.

    Returns

    Boolean | Object

    A booloan indicating that the event is to be canceled, or data returned by one of the listeners.

  • getByElement( element, [ checkWrapperOnly ] ) → widget

    See source

    Finds a widget instance which contains a given element. The element will be the wrapper of the returned widget or a descendant of this wrapper.

    editor.widgets.getByElement( someWidget.wrapper ); // -> someWidget
editor.widgets.getByElement( someWidget.parts.caption ); // -> someWidget

// Check wrapper only:
editor.widgets.getByElement( someWidget.wrapper, true ); // -> someWidget
editor.widgets.getByElement( someWidget.parts.caption, true ); // -> null

    Parameters

    element : element

    The element to be checked.

    [ checkWrapperOnly ] : Boolean

    If set to true, the method will not check wrappers' descendants.

    Returns

    widget

    The widget instance or null.

  • hasListeners( eventName ) → Boolean

    See source

    Checks if there is any listener registered to a given event.

    var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
alert( someObject.hasListeners( 'someEvent' ) );    // true
alert( someObject.hasListeners( 'noEvent' ) );      // false

    Parameters

    eventName : String

    The event name.

    Returns

    Boolean

  • initOn( element, [ widgetDef ], [ startupData ] ) → widget

    See source

    Initializes a widget on a given element if the widget has not been initialized on it yet.

    Parameters

    element : element

    The future widget element.

    [ widgetDef ] : String | definition

    Name of a widget or a widget definition. The widget definition should be previously registered by using the add method.

    [ startupData ] : Object

    Widget startup data (has precedence over default one).

    Returns

    widget

    The widget instance or null if a widget could not be initialized on a given element.

  • initOnAll( [ container ] ) → widget[]

    See source

    Initializes widgets on all elements which were wrapped by wrapElement and have not been initialized yet.

    Parameters

    [ container ] : element

    The container which will be checked for not initialized widgets. Defaults to editor's editable element.

    Defaults to editor.editable()

    Returns

    widget[]

    Array of widget instances which have been initialized. Note: Only first-level widgets are returned — without nested widgets.

  • on( eventName, listenerFunction, [ scopeObj ], [ listenerData ], [ priority ] ) → Object

    See source

    Registers a listener to a specific event in the current object.

    someObject.on( 'someEvent', function() {
    alert( this == someObject );        // true
} );

someObject.on( 'someEvent', function() {
    alert( this == anotherObject );     // true
}, anotherObject );

someObject.on( 'someEvent', function( event ) {
    alert( event.listenerData );        // 'Example'
}, null, 'Example' );

someObject.on( 'someEvent', function() { ... } );                       // 2nd called
someObject.on( 'someEvent', function() { ... }, null, null, 100 );      // 3rd called
someObject.on( 'someEvent', function() { ... }, null, null, 1 );        // 1st called

    Note: CKEditor's event system has a limitation that one function cannot be used as a listener for the same event more than once. Hence, to reuse it with multiple listeners, it should be wrapped into additional wrapper function:

    function listener( evt ) { ... };

someObject.on( 'someEvent', function() {
    listener();
} );

someObject.on( 'someEvent', function( evt ) {
    listener( evt );
} );

    Parameters

    eventName : String

    The event name to which listen.

    listenerFunction : Function

    The function listening to the event. A single CKEDITOR.eventInfo object instanced is passed to this function containing all the event data.

    [ scopeObj ] : Object

    The object used to scope the listener call (the this object). If omitted, the current object is used.

    [ listenerData ] : Object

    Data to be sent as the CKEDITOR.eventInfo.listenerData when calling the listener.

    [ priority ] : Number

    The listener priority. Lower priority listeners are called first. Listeners with the same priority value are called in registration order.

    Defaults to 10

    Returns

    Object

    An object containing the removeListener function, which can be used to remove the listener at any time.

  • since 4.5.0

    onWidget( widgetName, eventName, listenerFunction, [ scopeObj ], [ listenerData ], [ priority ] )

    See source

    Allows to listen to events on specific types of widgets, even if they are not created yet.

    Please note that this method inherits parameters from the CKEDITOR.event.on method with one extra parameter at the beginning which is the widget name.

    editor.widgets.onWidget( 'image', 'action', function( evt ) {
    // Event `action` occurs on `image` widget.
} );

    Parameters

    widgetName : String
    eventName : String
    listenerFunction : Function
    [ scopeObj ] : Object
    [ listenerData ] : Object
    [ priority ] : Number

    Defaults to 10

  • once()

    See source

    Similiar with on but the listener will be called only once upon the next event firing.

    CKEDITOR.event.on

  • since 4.4.0

    parseElementClasses( classes ) → Object

    See source

    Parses element classes string and returns an object whose keys contain class names. Skips all cke_* classes.

    This method is used by the CKEDITOR.plugins.widget.getClasses method and may be used when overriding that method.

    Parameters

    classes : String

    String (value of class attribute).

    Returns

    Object

    Object containing classes or null if no classes found.

  • removeAllListeners()

    See source

    Remove all existing listeners on this object, for cleanup purpose.

  • removeListener( eventName, listenerFunction )

    See source

    Unregisters a listener function from being called at the specified event. No errors are thrown if the listener has not been registered previously.

    var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener called.
someObject.removeListener( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener not called.

    Parameters

    eventName : String

    The event name.

    listenerFunction : Function

    The listener function to unregister.

  • wrapElement( element, [ widgetName ] ) → element | element

    See source

    Wraps an element with a widget's non-editable container.

    If this method is called on an CKEDITOR.htmlParser.element, then it will also take care of fixing the DOM after wrapping (the wrapper may not be allowed in element's parent).

    Parameters

    element : element | element

    The widget element to be wrapped.

    [ widgetName ] : String

    The name of the widget definition. Defaults to element's data-widget attribute value.

    Returns

    element | element

    The wrapper element or null if the widget definition of this name is not registered.

Static methods

  • mixed static

    implementOn( targetObject )

    See source

    Implements the CKEDITOR.event features in an object.

    var myObject = { message: 'Example' };
CKEDITOR.event.implementOn( myObject );

myObject.on( 'testEvent', function() {
    alert( this.message );
} );
myObject.fire( 'testEvent' ); // 'Example'

    Parameters

    targetObject : Object

    The object into which implement the features.

Events

  • checkSelection( evt )

    See source

    An event fired to trigger the selection check.

    See the checkSelection method.

    Parameters

    evt : eventInfo

  • checkWidgets( evt )

    See source

    An event fired by the the checkWidgets method.

    It can be canceled in order to stop the checkWidgets method execution or the event listener can modify the method's options.

    Parameters

    evt : eventInfo

  • instanceCreated( evt )

    See source

    An event fired when a widget instance is created, but before it is fully initialized.

    Parameters

    evt : eventInfo

  • instanceDestroyed( evt )

    See source

    An event fired when a widget instance was destroyed.

    See also CKEDITOR.plugins.widget.destroy.

    Parameters

    evt : eventInfo