CKEditor 4 Documentation

CKEDITOR.plugins.widget.repository

Mixins

Files

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.

Defined By

Properties

CKEDITOR.plugins.widget.repository
view source
: Numberprivate
Minimum interval between selection checks. ...

Minimum interval between selection checks.

Defaults to: 500

CKEDITOR.plugins.widget.repository
view source
: CKEDITOR.editorreadonly

The editor instance for which this repository was created.

The editor instance for which this repository was created.

CKEDITOR.plugins.widget.repository
view source
: CKEDITOR.plugins.widgetreadonly
The focused widget instance. ...

The focused widget instance. See also CKEDITOR.plugins.widget.focus and CKEDITOR.plugins.widget.blur events.

editor.on( 'selectionChange', function() {
    if ( editor.widgets.focused ) {
        // Do something when a widget is focused...
    }
} );
CKEDITOR.plugins.widget.repository
view source
: Objectreadonly
An object containing initialized widget instances (widget id => CKEDITOR.plugins.widget). ...

An object containing initialized widget instances (widget id => CKEDITOR.plugins.widget).

Defaults to: {}

CKEDITOR.plugins.widget.repository
view source
: Objectreadonly
A hash of registered widget definitions (definition name => CKEDITOR.plugins.widget.definition). ...

A hash of registered widget definitions (definition name => CKEDITOR.plugins.widget.definition).

To register a definition use the add method.

Defaults to: {}

CKEDITOR.plugins.widget.repository
view source
: CKEDITOR.plugins.widget[]readonly
An array of selected widget instances. ...

An array of selected widget instances.

Defaults to: []

CKEDITOR.plugins.widget.repository
view source
: CKEDITOR.plugins.widgetreadonly

The widget instance that contains the nested editable which is currently focused.

The widget instance that contains the nested editable which is currently focused.

Defined By

Methods

Creates a widget repository instance. ...

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 : CKEDITOR.editor

    The editor instance for which the repository will be created.

Returns

Overrides: CKEDITOR.event.constructor

CKEDITOR.plugins.widget.repository
view source
( name, widgetDef ) : CKEDITOR.plugins.widget.definition
Adds a widget definition to the repository. ...

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

Returns

CKEDITOR.plugins.widget.repository
view source
( callback )
Adds a callback for element upcasting. ...

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

Register event handler under the capturing stage on supported target. ...

Register event handler under the capturing stage on supported target.

CKEDITOR.plugins.widget.repository
view source
( )
Checks the selection to update widget states (selection and focus). ...

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

This method is triggered by the checkSelection event.

CKEDITOR.plugins.widget.repository
view source
( [options] )
Checks if all widget instances are still present in the DOM. ...

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 (optional)

    The options object.

    • initOnlyNew : Boolean (optional)

      Initializes widgets only on newly wrapped widget elements (those which still have the cke_widget_new class). When this option is set to true, widgets which were invalidated (e.g. by replacing with a cloned DOM structure) will not be reinitialized. This makes the check faster.

    • focusInited : Boolean (optional)

      If only one widget is initialized by the method, it will be focused.

Predefine some intrinsic properties on a specific event name. ...

Predefine some intrinsic properties on a specific event name.

Parameters

  • name : String

    The event name

  • meta : Object
    • errorProof : (optional)

      Whether the event firing should catch error thrown from a per listener call.

      Defaults to: false

CKEDITOR.plugins.widget.repository
view source
( widget )
Removes the widget from the editor and moves the selection to the closest editable position if the widget was focused...

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

Parameters

CKEDITOR.plugins.widget.repository
view source
( widget, [offline] )
Destroys the widget instance and all its nested widgets (widgets inside its nested editables). ...

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

Parameters

  • widget : CKEDITOR.plugins.widget

    The widget instance to be destroyed.

  • offline : Boolean (optional)

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

CKEDITOR.plugins.widget.repository
view source
( [offline], [container] )
Destroys all widget instances. ...

Destroys all widget instances.

Parameters

  • offline : Boolean (optional)

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

  • container : CKEDITOR.dom.element (optional)

    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.

CKEDITOR.plugins.widget.repository
view source
( container )
Finalizes a process of widget creation. ...

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 : CKEDITOR.dom.element/CKEDITOR.dom.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).

( eventName, [data], [editor] ) : Boolean/Object
Fires an specific event in the object. ...

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

Returns

  • Boolean/Object

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

( eventName, [data], [editor] ) : Boolean/Object
Fires an specific event in the object, releasing all listeners registered to that event. ...

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

Returns

  • Boolean/Object

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

CKEDITOR.plugins.widget.repository
view source
( element, [checkWrapperOnly] ) : CKEDITOR.plugins.widget
Finds a widget instance which contains a given element. ...

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 : CKEDITOR.dom.element

    The element to be checked.

  • checkWrapperOnly : Boolean (optional)

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

Returns

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

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
CKEDITOR.plugins.widget.repository
view source
( element, [widgetDef], [startupData] ) : CKEDITOR.plugins.widget
Initializes a widget on a given element if the widget has not been initialized on it yet. ...

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

Parameters

  • element : CKEDITOR.dom.element

    The future widget element.

  • widgetDef : String/CKEDITOR.plugins.widget.definition (optional)

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

  • startupData : Object (optional)

    Widget startup data (has precedence over default one).

Returns

CKEDITOR.plugins.widget.repository
view source
( [container] ) : CKEDITOR.plugins.widget[]
Initializes widgets on all elements which were wrapped by wrapElement and have not been initialized yet. ...

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

Parameters

  • container : CKEDITOR.dom.element (optional)

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

    Defaults to: editor.editable()

Returns

  • CKEDITOR.plugins.widget[]

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

( eventName, listenerFunction, [scopeObj], [listenerData], [priority] ) : Object
Registers a listener to a specific event in the current object. ...

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

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 (optional)

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

  • listenerData : Object (optional)

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

  • priority : Number (optional)

    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.

CKEDITOR.plugins.widget.repository
view source
( widgetName, eventName, listenerFunction, [scopeObj], [listenerData], [priority] )
Allows to listen to events on specific types of widgets, even if they are not created yet. ...

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

Available since: 4.5

Parameters

  • widgetName : String
  • eventName : String
  • listenerFunction : Function
  • scopeObj : Object (optional)
  • listenerData : Object (optional)
  • priority : Number (optional)

    Defaults to: 10

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

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

CKEDITOR.event.on

CKEDITOR.plugins.widget.repository
view source
( classes ) : Object
Parses element classes string and returns an object whose keys contain class names. ...

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.

Available since: 4.4

Parameters

  • classes : String

    String (value of class attribute).

Returns

  • Object

    Object containing classes or null if no classes found.

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

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

( eventName, listenerFunction )
Unregisters a listener function from being called at the specified event. ...

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.

CKEDITOR.plugins.widget.repository
view source
( element, [widgetName] ) : CKEDITOR.dom.element/CKEDITOR.htmlParser.element
Wraps an element with a widget's non-editable container. ...

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

Returns

Defined By

Events

CKEDITOR.plugins.widget.repository
view source
( evt )
An event fired to trigger the selection check. ...

An event fired to trigger the selection check.

See the checkSelection method.

Parameters

CKEDITOR.plugins.widget.repository
view source
( evt )
An event fired by the the checkWidgets method. ...

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 : CKEDITOR.eventInfo
    • data : Object (optional)
      • initOnlyNew : Boolean (optional)

        Initialize widgets only on newly wrapped widget elements (those which still have the cke_widget_new class). When this option is set to true, widgets which were invalidated (e.g. by replacing with a cloned DOM structure) will not be reinitialized. This makes the check faster.

      • focusInited : Boolean (optional)

        If only one widget is initialized by the method, it will be focused.

CKEDITOR.plugins.widget.repository
view source
( evt )
An event fired when a widget instance is created, but before it is fully initialized. ...

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

Parameters

CKEDITOR.plugins.widget.repository
view source
( evt )
An event fired when a widget instance was destroyed. ...

An event fired when a widget instance was destroyed.

See also CKEDITOR.plugins.widget.destroy.

Parameters