CKEditor 4 Documentation

CKEDITOR.plugins.widget

Hierarchy

CKEDITOR.plugins.widget.definition
CKEDITOR.plugins.widget

Mixins

Inherited mixins

Files

An instance of a widget. Together with CKEDITOR.plugins.widget.repository these two classes constitute the core of the Widget System.

Note that neither the repository nor the widget instances can be created by using their constructors. A repository instance is automatically set up by the Widget plugin and is accessible under CKEDITOR.editor.widgets, while widget instances are created and destroyed by the repository.

To create a widget, first you need to register its definition:

editor.widgets.add( 'simplebox', {
    upcast: function( element ) {
        // Defines which elements will become widgets.
        if ( element.hasClass( 'simplebox' ) )
            return true;
    },
    init: function() {
        // ...
    }
} );

Once the widget definition is registered, widgets will be automatically created when loading data:

editor.setData( '<div class="simplebox">foo</div>', function() {
    console.log( editor.widgets.instances ); // -> An object containing one instance.
} );

It is also possible to create instances during runtime by using a command (if a CKEDITOR.plugins.widget.definition.template property was defined):

// You can execute an automatically defined command to
// insert a new simplebox widget or edit the one currently focused.
editor.execCommand( 'simplebox' );

Note: Since CKEditor 4.5 widget's startupData can be passed as the command argument:

editor.execCommand( 'simplebox', {
    startupData: {
        align: 'left'
    }
} );

A widget can also be created in a completely custom way:

var element = editor.document.createElement( 'div' );
editor.insertElement( element );
var widget = editor.widgets.initOn( element, 'simplebox' );

Available since: 4.3

Properties

Defined By

Instance properties

HTML code that can be generated by this feature. ...

HTML code that can be generated by this feature.

For example a basic image feature (image button displaying the image dialog window) may allow 'img[!src,alt,width,height]'.

During the feature activation this value is passed to CKEDITOR.filter.allow.

Defaults to: null

The label for the widget toolbar button. ...

The label for the widget toolbar button.

editor.widgets.add( 'simplebox', {
    button: 'Create a simple box'
} );

editor.widgets.add( 'simplebox', {
    button: editor.lang.simplebox.title
} );
Feature content forms to be registered in the CKEDITOR.editor.filter during the feature activation. ...

Feature content forms to be registered in the CKEDITOR.editor.filter during the feature activation.

See CKEDITOR.filter.addContentForms for more details.

Defaults to: null

Transformations (usually for content generated by this feature, but not necessarily) that will be registered in the C...

Transformations (usually for content generated by this feature, but not necessarily) that will be registered in the CKEDITOR.editor.filter during the feature activation.

See CKEDITOR.filter.addTransformations for more details.

Defaults to: null

CKEDITOR.plugins.widget
view source
: Objectreadonly
Widget's data object. ...

Widget's data object.

The data can only be set by using the setData method. Changes made to the data fire the data event.

Overrides: CKEDITOR.plugins.widget.definition.data

CKEDITOR.plugins.widget
view source
: Booleanreadonly
Indicates if a widget is data-ready. ...

Indicates if a widget is data-ready. Set to true when data from all sources (CKEDITOR.plugins.widget.definition.defaults, set in the init method, loaded from the widget's element and startup data coming from the constructor) are finally loaded. This is immediately followed by the first data.

Defaults to: false

The data object which will be used to populate the data of a newly created widget. ...

The data object which will be used to populate the data of a newly created widget. See CKEDITOR.plugins.widget.data.

defaults: {
    showCaption: true,
    align: 'none'
}

The widget definition from which this instance was created.

The widget definition from which this instance was created.

The name of a dialog window which will be opened on CKEDITOR.plugins.widget.edit. ...

The name of a dialog window which will be opened on CKEDITOR.plugins.widget.edit. If not defined, then the CKEDITOR.plugins.widget.edit method will not perform any action and widget's command will insert a new widget without opening a dialog window first.

The function to be used to downcast this widget or a name of the downcast option from the downcasts object. ...

The function to be used to downcast this widget or a name of the downcast option from the downcasts object.

The downcast funciton will be executed in the CKEDITOR.plugins.widget context and with widgetElement (CKEDITOR.htmlParser.element) argument which is the widget's main element.

The function may return an instance of the CKEDITOR.htmlParser.node class if the widget needs to be downcasted to a different node than the widget's main element.

The object containing functions which can be used to downcast this widget. ...

The object containing functions which can be used to downcast this widget. Only the one pointed by the downcast property will be used.

In most cases it is appropriate to use downcast directly, because majority of widgets have just one variant of downcasting (or none at all). However, in some cases the widget author may want to expose more than one variant and then this property may be used.

downcasts: {
    // This downcast may transform the widget into the figure element.
    figure: function() {
        // ...
    },
    // This downcast may transform the widget into the image element with data-* attributes.
    image: function() {
        // ...
    }
}

// Then, the widget user may choose one of the downcast options when setting up his editor.
editor.on( 'widgetDefinition', function( evt ) {
    if ( evt.data.name == 'image' )
            evt.data.downcast = 'figure';
} );
Whether widget should be draggable. ...

Whether widget should be draggable. Defaults to true. If set to false drag handler will not be displayed when hovering widget.

If set, it will be added as the CKEDITOR.plugins.widget.edit event listener. ...

If set, it will be added as the CKEDITOR.plugins.widget.edit event listener. This means that it will be executed when a widget is being edited. See the CKEDITOR.plugins.widget.edit method.

An object containing definitions of nested editables (editable name => CKEDITOR.plugins.widget.nestedEditable.definit...

An object containing definitions of nested editables (editable name => CKEDITOR.plugins.widget.nestedEditable.definition). Note that editables have to be defined in the same order as they are in DOM / template. Otherwise errors will occur when nesting widgets inside each other.

editables: {
    header: 'h1',
    content: {
        selector: 'div.content',
        allowedContent: 'p strong em; a[!href]'
    }
}
CKEDITOR.plugins.widget
view source
: CKEDITOR.editorreadonly

The editor instance.

The editor instance.

CKEDITOR.plugins.widget
view source
: CKEDITOR.dom.elementreadonly

The widget element — the element on which the widget was initialized.

The widget element — the element on which the widget was initialized.

The nested editable element which is currently focused.

The nested editable element which is currently focused.

The function used to obtain an accessibility label for the widget. ...

The function used to obtain an accessibility label for the widget. It might be used to make the widget labels as precise as possible, since it has access to the widget instance.

If not specified, the default implementation will use the pathName or the main element tag name.

CKEDITOR.plugins.widget
view source
: Numberreadonly

This widget's unique (per editor instance) ID.

This widget's unique (per editor instance) ID.

The method executed while initializing a widget, after a widget instance is created, but before it is ready. ...

The method executed while initializing a widget, after a widget instance is created, but before it is ready. It is executed before the first CKEDITOR.plugins.widget.data is fired so it is common to use the init method to populate widget data with information loaded from the DOM, like for exmaple:

init: function() {
    this.setData( 'width', this.element.getStyle( 'width' ) );

    if ( this.parts.caption.getStyle( 'display' ) != 'none' )
        this.setData( 'showCaption', true );
}
CKEDITOR.plugins.widget
view source
: Booleanreadonly
Whether a widget instance was initialized. ...

Whether a widget instance was initialized. This means that:

  • An instance was created,
  • Its properties were set,
  • The init method was executed.

Note: The first data event could not be fired yet which means that the widget's DOM has not been set up yet. Wait for the ready event to be notified when a widget is fully initialized and ready.

Note: Use the isInited method to check whether a widget is initialized and has not been destroyed.

Defaults to: false

CKEDITOR.plugins.widget
view source
: Booleanreadonly
Whether this widget is an inline widget (based on an inline element unless forced otherwise by CKEDITOR.plugins.widge...

Whether this widget is an inline widget (based on an inline element unless forced otherwise by CKEDITOR.plugins.widget.definition.inline).

Note: This option does not allow to turn a block element into an inline widget. However, it makes it possible to turn an inline element into a block widget or to force a correct type in case when automatic recognition fails.

Overrides: CKEDITOR.plugins.widget.definition.inline

The method to be executed when the widget's command is executed in order to insert a new widget (widget of this type ...

The method to be executed when the widget's command is executed in order to insert a new widget (widget of this type is not focused). If not defined, then the default action will be performed which means that:

If set to true, the widget's element will be covered with a transparent mask. ...

If set to true, the widget's element will be covered with a transparent mask. This will prevent its content from being clickable, which matters in case of special elements like embedded Flash or iframes that generate a separate "context".

Widget definition name. ...

Widget definition name. It is automatically set when the definition is registered.

Overrides: CKEDITOR.feature.name

CKEDITOR.plugins.widget
view source
: Objectreadonly
An object of widget component elements. ...

An object of widget component elements.

For every partName => selector pair in CKEDITOR.plugins.widget.definition.parts, one partName => element pair is added to this object during the widget initialization.

Overrides: CKEDITOR.plugins.widget.definition.parts

The widget name displayed in the elements path.

The widget name displayed in the elements path.

CKEDITOR.plugins.widget
view source
: Booleanreadonly
Whether a widget instance is ready. ...

Whether a widget instance is ready. This means that the widget is inited and that its DOM was finally set up.

Note: Use the isReady method to check whether a widget is ready and has not been destroyed.

Defaults to: false

Link to the widget repository which created this instance.

Link to the widget repository which created this instance.

Minimal HTML code that this feature must be allowed to generate in order to work. ...

Minimal HTML code that this feature must be allowed to generate in order to work.

For example a basic image feature (image button displaying the image dialog window) needs 'img[src,alt]' in order to be activated.

During the feature validation this value is passed to CKEDITOR.filter.check.

If this value is not provided, a feature will be always activated.

Defaults to: null

Function transforming custom widget's CKEDITOR.style instance into CKEDITOR.filter.allowedContentRules. ...

Function transforming custom widget's CKEDITOR.style instance into CKEDITOR.filter.allowedContentRules. It may be used when a static styleableElements property is not enough to inform the CKEDITOR.filter what HTML features should be enabled when allowing the given style.

In most cases, when style's classes just have to be added to element name(s) used by the widget element, it is recommended to use simpler styleableElements property.

In order to get parsed classes from the style definition you can use CKEDITOR.style.customHandlers.widget.getClassesArray.

For example, if you want to use the object format of allowed content rules, to specify match validator, your implementation could look like this:

editor.widgets.add( 'customWidget', {
    // ...

    styleToAllowedContentRules: funciton( style ) {
        // Retrieve classes defined in the style.
        var classes = style.getClassesArray();

        // Do something crazy - for example return allowed content rules in object format,
        // with custom match property and propertiesOnly flag.
        return {
            h1: {
                match: isWidgetElement,
                propertiesOnly: true,
                classes: classes
            }
        };
    }
} );

Available since: 4.4

Parameters

Returns

Names of element(s) (separated by spaces) for which the CKEDITOR.filter should allow classes defined in the widget st...

Names of element(s) (separated by spaces) for which the CKEDITOR.filter should allow classes defined in the widget styles. For example if your widget is upcasted from a simple <div> element, then in order to make it styleable you can set:

editor.widgets.add( 'customWidget', {
    upcast: function( element ) {
        return element.name == 'div';
    },

    // ...

    styleableElements: 'div'
} );

Then, when the following style is defined:

{
    name: 'Thick border', type: 'widget', widget: 'customWidget',
    attributes: { 'class': 'thickBorder' }
}

a rule allowing the thickBorder class for div elements will be registered in the CKEDITOR.filter.

If you need to have more freedom when transforming widget style to allowed content rules, you can use the styleToAllowedContentRules callback.

Available since: 4.4

CKEDITOR.plugins.widget
view source
: CKEDITOR.templatereadonly
The template which will be used to create a new widget element (when the widget's command is executed). ...

The template which will be used to create a new widget element (when the widget's command is executed). It will be populated with default values.

Overrides: CKEDITOR.plugins.widget.definition.template

The function to be used to upcast an element to this widget or a comma-separated list of upcast methods from the upca...

The function to be used to upcast an element to this widget or a comma-separated list of upcast methods from the upcasts object.

The upcast function is not executed in the widget context (because the widget does not exist yet) and two arguments are passed:

  • element (CKEDITOR.htmlParser.element) – The element to be checked.
  • data (Object) – The object which can be extended with data which will then be passed to the widget.

An element will be upcasted if a function returned true or an instance of a CKEDITOR.htmlParser.element if upcasting meant DOM structure changes (in this case the widget will be initialized on the returned element).

The upcast method(s) priority. ...

The upcast method(s) priority. The upcast with a lower priority number will be called before the one with a higher number. The default priority is 10.

Defaults to: 10

Available since: 4.5

The object containing functions which can be used to upcast this widget. ...

The object containing functions which can be used to upcast this widget. Only those pointed by the upcast property will be used.

In most cases it is appropriate to use upcast directly, because majority of widgets need just one method. However, in some cases the widget author may want to expose more than one variant and then this property may be used.

upcasts: {
    // This function may upcast only figure elements.
    figure: function() {
        // ...
    },
    // This function may upcast only image elements.
    image: function() {
        // ...
    },
    // More variants...
}

// Then, widget user may choose which upcast methods will be enabled.
editor.on( 'widgetDefinition', function( evt ) {
    if ( evt.data.name == 'image' )
            evt.data.upcast = 'figure,image'; // Use both methods.
} );
CKEDITOR.plugins.widget
view source
: CKEDITOR.dom.elementreadonly
The widget wrapper — a non-editable div or span element (depending on inline) which is a parent of the element ...

The widget wrapper — a non-editable div or span element (depending on inline) which is a parent of the element and widget compontents like the drag handler and the mask. It is the outermost widget element.

Defined By

Static properties

CKEDITOR.plugins.widget
view source
: Stringreadonlystatic
Prefix added to wrapper classes. ...

Prefix added to wrapper classes. Each class added to the widget element by the addClass method will also be added to the wrapper prefixed with it.

Defaults to: 'cke_widget_wrapper_'

Available since: 4.6.0

Methods

Defined By

Instance methods

CKEDITOR.plugins.widget
view source
new( widgetsRepo, id, element, widgetDef, [startupData] ) : CKEDITOR.plugins.widget
Creates an instance of the widget class. ...

Creates an instance of the widget class. Do not use it directly, but instead initialize widgets by using the CKEDITOR.plugins.widget.repository.initOn method or by the upcasting system.

Parameters

Returns

Overrides: CKEDITOR.event.constructor

CKEDITOR.plugins.widget
view source
( selector ) : CKEDITOR.dom.elementprivate
Looks inside wrapper element to find a node that matches given selector and is not nested in other widget. ...

Looks inside wrapper element to find a node that matches given selector and is not nested in other widget. (http://dev.ckeditor.com/ticket/13334)

Available since: 4.5

Parameters

  • selector : String

    Selector to match.

Returns

CKEDITOR.plugins.widget
view source
( className )
Adds a class to the widget element. ...

Adds a class to the widget element. This method is used by the applyStyle method and should be overridden by widgets which should handle classes differently (e.g. add them to other elements).

Since 4.6.0 this method also adds a corresponding class prefixed with WRAPPER_CLASS_PREFIX to the widget wrapper element.

Note: This method should not be used directly. Use the setData method to set the classes property. Read more in the setData documentation.

See also: removeClass, hasClass, getClasses.

Available since: 4.4

Parameters

  • className : String

    The class name to be added.

CKEDITOR.plugins.widget
view source
( style )
Applies the specified style to the widget. ...

Applies the specified style to the widget. It is highly recommended to use the CKEDITOR.editor.applyStyle or CKEDITOR.style.apply methods instead of using this method directly, because unlike editor's and style's methods, this one does not perform any checks.

By default this method handles only classes defined in the style. It clones existing classes which are stored in the widget data's classes property, adds new classes, and calls the setData method if at least one new class was added. Then, using the data event listener widget applies modifications passing new classes to the addClass method.

If you need to handle classes differently than in the default way, you can override the addClass and related methods. You can also handle other style properties than classes by overriding this method.

See also: checkStyleActive, removeStyle.

Available since: 4.4

Parameters

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

Register event handler under the capturing stage on supported target.

CKEDITOR.plugins.widget
view source
( style ) : Boolean
Checks if the specified style is applied to this widget. ...

Checks if the specified style is applied to this widget. It is highly recommended to use the CKEDITOR.style.checkActive method instead of using this method directly, because unlike style's method, this one does not perform any checks.

By default this method handles only classes defined in the style and passes them to the hasClass method. You can override these methods to handle classes differently or to handle more of the style properties.

See also: applyStyle, removeStyle.

Available since: 4.4

Parameters

Returns

  • Boolean

    Whether the style is applied to this widget.

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
view source
( [offline] )
Destroys this widget instance. ...

Destroys this widget instance.

Use CKEDITOR.plugins.widget.repository.destroy when possible instead of this method.

This method fires the {#event-destroy} event.

Parameters

  • offline : Boolean (optional)

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

CKEDITOR.plugins.widget
view source
( editableName, [offline] )
Destroys a nested editable and all nested widgets. ...

Destroys a nested editable and all nested widgets.

Parameters

  • editableName : String

    Nested editable name.

  • offline : Boolean (optional)

    See destroy method.

CKEDITOR.plugins.widget
view source
( ) : Boolean
Starts widget editing. ...

Starts widget editing.

This method fires the edit event which may be canceled in order to prevent it from opening a dialog window.

The dialog window name is obtained from the event's data dialog property or from CKEDITOR.plugins.widget.definition.dialog.

Returns

  • Boolean

    Returns true if a dialog window was opened.

( 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
view source
( )
Focuses a widget by selecting it. ...

Focuses a widget by selecting it.

CKEDITOR.plugins.widget
view source
( ) : Object
Returns widget element classes parsed to an object. ...

Returns widget element classes parsed to an object. This method is used to populate the classes property of widget's data.

This method reuses CKEDITOR.plugins.widget.repository.parseElementClasses. It should be overriden if a widget should handle classes differently (e.g. on other elements).

See also: removeClass, addClass, hasClass.

Available since: 4.4

Returns

  • Object
CKEDITOR.plugins.widget
view source
( className, Whether )
Checks if the widget element has specified class. ...

Checks if the widget element has specified class. This method is used by the checkStyleActive method and should be overriden by widgets which should handle classes differently (e.g. on other elements).

See also: removeClass, addClass, getClasses.

Available since: 4.4

Parameters

  • className : String

    The class to be checked.

  • Whether : Boolean

    a widget has specified class.

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
view source
( editableName, definition ) : Boolean
Initializes a nested editable. ...

Initializes a nested editable.

Note: Only elements from CKEDITOR.dtd.$editable may become editables.

Parameters

Returns

  • Boolean

    Whether an editable was successfully initialized.

CKEDITOR.plugins.widget
view source
( ) : Boolean
Checks if a widget has already been initialized and has not been destroyed yet. ...

Checks if a widget has already been initialized and has not been destroyed yet.

See inited for more details.

Returns

  • Boolean
CKEDITOR.plugins.widget
view source
( ) : Boolean
Checks if a widget is ready and has not been destroyed yet. ...

Checks if a widget is ready and has not been destroyed yet.

See ready for more details.

Returns

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

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

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

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

CKEDITOR.plugins.widget
view source
( className )
Removes a class from the widget element. ...

Removes a class from the widget element. This method is used by the removeStyle method and should be overriden by widgets which should handle classes differently (e.g. on other elements).

Note: This method should not be used directly. Use the setData method to set the classes property. Read more in the setData documentation.

See also: hasClass, addClass.

Available since: 4.4

Parameters

  • className : String

    The class to be removed.

( 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
view source
( style )
Removes the specified style from the widget. ...

Removes the specified style from the widget. It is highly recommended to use the CKEDITOR.editor.removeStyle or CKEDITOR.style.remove methods instead of using this method directly, because unlike editor's and style's methods, this one does not perform any checks.

Read more about how applying/removing styles works in the applyStyle method documentation.

See also checkStyleActive, applyStyle, getClasses.

Available since: 4.4

Parameters

CKEDITOR.plugins.widget
view source
( keyOrData, value ) : CKEDITOR.plugins.widgetchainable
Sets widget value(s) in the data object. ...

Sets widget value(s) in the data object. If the given value(s) modifies current ones, the data event is fired.

this.setData( 'align', 'left' );
this.data.align; // -> 'left'

this.setData( { align: 'right', opened: false } );
this.data.align; // -> 'right'
this.data.opened; // -> false

Set values are stored in element's attribute (data-cke-widget-data), in a JSON string, therefore data should contain only serializable data.

Note: A special data property, classes, exists. It contains an object with classes which were returned by the getClasses method during the widget initialization. This property is then used by the applyStyle and removeStyle methods. When it is changed (the reference to object must be changed!), the widget updates its classes by using the addClass and removeClass methods.

// Adding a new class.
var classes = CKEDITOR.tools.clone( widget.data.classes );
classes.newClass = 1;
widget.setData( 'classes', classes );

// Removing a class.
var classes = CKEDITOR.tools.clone( widget.data.classes );
delete classes.newClass;
widget.setData( 'classes', classes );

Parameters

  • keyOrData : String/Object
  • value : Object

Returns

CKEDITOR.plugins.widget
view source
( selected ) : CKEDITOR.plugins.widgetchainable
Changes the widget's focus state. ...

Changes the widget's focus state. This method is executed automatically after a widget was focused by the focus method or the selection was moved out of the widget.

This is a low-level method which is not integrated with e.g. the undo manager. Use the focus method instead.

Parameters

  • selected : Boolean

    Whether to select or deselect this widget.

Returns

CKEDITOR.plugins.widget
view source
( selected ) : CKEDITOR.plugins.widgetchainable
Changes the widget's select state. ...

Changes the widget's select state. This method is executed automatically after a widget was selected by the focus method or the selection was moved out of the widget.

This is a low-level method which is not integrated with e.g. the undo manager. Use the focus method instead or simply change the selection.

Parameters

  • selected : Boolean

    Whether to select or deselect this widget.

Returns

Returns a feature that this feature needs to register. ...

Returns a feature that this feature needs to register.

In some cases, during activation, one feature may need to register another feature. For example a CKEDITOR.ui.button often registers a related command. See CKEDITOR.ui.button.toFeature.

This method is executed when a feature is passed to the CKEDITOR.editor.addFeature.

Returns

CKEDITOR.plugins.widget
view source
( )
Repositions drag handler according to the widget's element position. ...

Repositions drag handler according to the widget's element position. Should be called from events, like mouseover.

Defined By

Static methods

CKEDITOR.plugins.widget
view source
( guard, node ) : CKEDITOR.dom.element/nullstatic
Gets the nested editable (returned as a CKEDITOR.dom.element, not as a CKEDITOR.plugins.widget.nestedEditable) closes...

Gets the nested editable (returned as a CKEDITOR.dom.element, not as a CKEDITOR.plugins.widget.nestedEditable) closest to the node or the node if it is a nested editable itself.

Available since: 4.5

Parameters

Returns

CKEDITOR.plugins.widget
view source
( node ) : Booleanstatic
Checks whether the node is a widget's drag handle element. ...

Checks whether the node is a widget's drag handle element.

Available since: 4.5

Parameters

Returns

  • Boolean
CKEDITOR.plugins.widget
view source
( node ) : Booleanstatic
Checks whether the node is a container of the widget's drag handle element. ...

Checks whether the node is a container of the widget's drag handle element.

Available since: 4.5

Parameters

Returns

  • Boolean
CKEDITOR.plugins.widget
view source
( node ) : Booleanstatic
Checks whether the node is a nested editable. ...

Checks whether the node is a nested editable. Note that this function only checks whether it is the right element, not whether the passed node is an instance of CKEDITOR.plugins.widget.nestedEditable.

Available since: 4.5

Parameters

Returns

  • Boolean
CKEDITOR.plugins.widget
view source
( node ) : Booleanstatic
Checks whether the node is a widget element. ...

Checks whether the node is a widget element.

Available since: 4.5

Parameters

Returns

  • Boolean
CKEDITOR.plugins.widget
view source
( node ) : Booleanstatic
Checks whether the node is a widget wrapper. ...

Checks whether the node is a widget wrapper.

Available since: 4.5

Parameters

Returns

  • Boolean
CKEDITOR.plugins.widget
view source
( node ) : Booleanstatic
Checks whether the node is a widget element. ...

Checks whether the node is a widget element.

Available since: 4.5

Parameters

Returns

  • Boolean
CKEDITOR.plugins.widget
view source
( node ) : Booleanstatic
Checks whether the node is a widget wrapper. ...

Checks whether the node is a widget wrapper.

Available since: 4.5

Parameters

Returns

  • Boolean
Defined By

Events

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a widget is blurred. ...

An event fired when a widget is blurred.

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when the context menu is opened for a widget. ...

An event fired when the context menu is opened for a widget.

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when the widget data changed. ...

An event fired when the widget data changed. See the setData method and the data property.

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a widget is deselected. ...

An event fired when a widget is deselected.

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a widget is about to be destroyed, but before it is fully torn down. ...

An event fired when a widget is about to be destroyed, but before it is fully torn down.

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a dialog window for widget editing is opened. ...

An event fired when a dialog window for widget editing is opened. This event can be canceled in order to handle the editing dialog in a custom manner.

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a widget is double clicked. ...

An event fired when a widget is double clicked.

Note: If a default editing action is executed on double click (i.e. a widget has a dialog defined and the doubleclick event was not canceled), this event will be automatically canceled, so a listener added with the default priority (10) will not be executed. Use a listener with low priority (e.g. 5) to be sure that it will be executed.

widget.on( 'doubleclick', function( evt ) {
    console.log( 'widget#doubleclick' );
}, null, null, 5 );

If your widget handles double click in a special way (so the default editing action is not executed), make sure you cancel this event, because otherwise it will be propagated to CKEDITOR.editor.doubleclick and another feature may step in (e.g. a Link dialog window may be opened if your widget was inside a link).

Parameters

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

An event fired by the edit method. It can be canceled in order to stop the default action (opening a dialog window and/or finalizing widget creation).

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a widget is focused. ...

An event fired when a widget is focused.

Widget can be focused by executing focus.

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a key is pressed on a focused widget. ...

An event fired when a key is pressed on a focused widget. This event is forwarded from the CKEDITOR.editor.key event and has the ability to block editor keystrokes if it is canceled.

Parameters

  • evt : CKEDITOR.eventInfo
    • data : Object
      • keyCode : Number

        A number representing the key code (or combination).

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a widget is ready (fully initialized). ...

An event fired when a widget is ready (fully initialized). This event is fired after:

  • init is called,
  • The first data event is fired,
  • A widget is attached to the document.

Therefore, in case of widget creation with a command which opens a dialog window, this event will be delayed after the dialog window is closed and the widget is finally inserted into the document.

Note: If your widget does not use automatic dialog window binding (i.e. you open the dialog window manually) or another situation in which the widget wrapper is not attached to document at the time when it is initialized occurs, you need to take care of firing ready yourself.

See also ready and inited properties, and isReady and isInited methods.

Parameters

CKEDITOR.plugins.widget
view source
( evt )
An event fired when a widget is selected. ...

An event fired when a widget is selected.

Parameters