CKEDITOR.plugins.widget

class since 4.3

Hierarchy

definition
- widget

Mixes

event
feature

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

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

allowedContent : allowedContentRules

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

`button : String`

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

contentForms : Object

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

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

readonly

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
dataReady : Boolean

readonly

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
defaults : Object
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'
}
```
definition : definition

readonly

The widget definition from which this instance was created.
dialog : String

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.
downcast : String | Function

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

The downcast function 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.

`downcasts : Object`

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

draggable : Boolean

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

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.
editables : Object
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]'
    }
}
```
editor : editor

readonly

The editor instance.
element : element

readonly

The widget element — the element on which the widget was initialized.
focusedEditable : nestedEditable

readonly

The nested editable element which is currently focused.
getLabel : Function

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.
id : Number

readonly

This widget's unique (per editor instance) ID.
init : Function
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 );
}
```
inited : Boolean

readonly
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
inline : Boolean

readonly

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
insert : Function
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:
- An instance of the widget will be created in a detached document fragment,
- The CKEDITOR.plugins.widget.edit method will be called to trigger widget editing,
- The widget element will be inserted into DOM.
mask : Boolean

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".
name : String

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

Overrides: CKEDITOR.feature.name
parts : Object

readonly

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
pathName : String

The widget name displayed in the elements path.
ready : Boolean

readonly

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

readonly

Link to the widget repository which created this instance.
requiredContent : contentRule

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
styleToAllowedContentRules : Function

since 4.4
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
            }
        };
    }
} );
```
styleableElements : String

since 4.4
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.
template : template

readonly

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
upcast : String | Function
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), however, it is executed in the widget's definition context. Two arguments are passed to the upcast function:
- 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).
upcastPriority : Number

since 4.5

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

`upcasts : Object`

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

wrapper : element

readonly

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.

Static properties

WRAPPER_CLASS_PREFIX : String

since 4.6.0 readonly static

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_'
useCapture : Boolean

mixed static

Methods

constructor( widgetsRepo, id, element, widgetDef, [ startupData ] ) → widget

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

widgetsRepo : repository

id : Number

Unique ID of this widget instance.

element : element

The widget element.

widgetDef : definition

Widget's registered definition.

[ startupData ] : Object

Initial widget data. This data object will overwrite the default data and the data loaded from the DOM.

Returns

widget

Overrides: CKEDITOR.event.constructor
addClass( className )

since 4.4

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.

Parameters

className : String

The class name to be added.
applyStyle( style )

since 4.4

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.

Parameters

style : style

The custom widget style to be applied.
capture()

Register event handler under the capturing stage on supported target.
checkStyleActive( style ) → Boolean

since 4.4

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.

Parameters

style : style

The custom widget style to be checked.

Returns

Boolean

Whether the style is applied to this widget.
define( name, meta )

Predefine some intrinsic properties on a specific event name.

Parameters

name : String

The event name

meta : Object

Properties

[ errorProof ]

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

Defaults to false
destroy( [ offline ] )

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

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

Destroys a nested editable and all nested widgets.

Parameters

editableName : String

Nested editable name.

[ offline ] : Boolean

See destroy method.
edit() → Boolean

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.
fire( eventName, [ data ], [ editor ] ) → Boolean | 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

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

Focuses a widget by selecting it.
getClasses() → Object

since 4.4

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.

Returns

Object
hasClass( className, Whether )

since 4.4

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.

Parameters

className : String

The class to be checked.

Whether : Boolean

a widget has specified class.
hasListeners( eventName ) → Boolean
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
initEditable( editableName, definition ) → Boolean

Initializes a nested editable.

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

Parameters

editableName : String

The nested editable name.

definition : definition

The definition of the nested editable.

Returns

Boolean

Whether an editable was successfully initialized.
isInited() → Boolean

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

See inited for more details.

Returns

Boolean
isReady() → Boolean

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

See ready for more details.

Returns

Boolean
on( eventName, listenerFunction, [ scopeObj ], [ listenerData ], [ priority ] ) → 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

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

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

CKEDITOR.event.on
removeAllListeners()

Remove all existing listeners on this object, for cleanup purpose.
removeClass( className )

since 4.4

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.

Parameters

className : String

The class to be removed.
removeListener( eventName, listenerFunction )
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.
removeStyle( style )

since 4.4

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.

Parameters

style : style

The custom widget style to be removed.
setData( keyOrData, value ) → widget

chainable
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

widget

this
setFocused( selected ) → widget

chainable

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

widget

this
setSelected( selected ) → widget

chainable

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

widget

this
toFeature() → feature

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

feature
updateDragHandlerPosition()

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

since 4.5 private

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

Parameters

selector : String

Selector to match.

Returns

element

Matched element or null if a node has not been found.

Static methods

getNestedEditable( guard, node ) → element | null

since 4.5 static

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.

Parameters

guard : element

Stop ancestor search on this node (usually editor's editable).

node : node

Start the search from this node.

Returns

element | null

Element or null if not found.
isDomDragHandler( node ) → Boolean

since 4.5 static

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

Parameters

node : node

Returns

Boolean
isDomDragHandlerContainer( node ) → Boolean

since 4.5 static

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

Parameters

node : node

Returns

Boolean
isDomNestedEditable( node ) → Boolean

since 4.5 static

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.

Parameters

node : node

Returns

Boolean
isDomWidget( node ) → Boolean

since 4.8.0 static

Checks whether the node is a DOM widget.

Parameters

node : node

Returns

Boolean
isDomWidgetElement( node ) → Boolean

since 4.5 static

Checks whether the node is a widget element.

Parameters

node : node

Returns

Boolean
isDomWidgetWrapper( node ) → Boolean

since 4.5 static

Checks whether the node is a widget wrapper.

Parameters

node : element

Returns

Boolean
isParserWidgetElement( node ) → Boolean

since 4.5 static

Checks whether the node is a widget element.

Parameters

node : node

Returns

Boolean
isParserWidgetWrapper( node ) → Boolean

since 4.5 static

Checks whether the node is a widget wrapper.

Parameters

node : element

Returns

Boolean

Events

blur( evt )

An event fired when a widget is blurred.

Parameters

evt : eventInfo
contextMenu( evt )

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

Parameters

evt : eventInfo

Properties

data : Object

The object containing context menu options to be added for this widget. See CKEDITOR.plugins.contextMenu.addListener.
data( evt )

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

Parameters

evt : eventInfo
deselect( evt )

An event fired when a widget is deselected.

Parameters

evt : eventInfo
destroy( evt )

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

Parameters

evt : eventInfo
dialog( evt )

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

evt : eventInfo

Properties

data : dialog

The opened dialog window instance.
doubleclick( evt )
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

evt : eventInfo

Properties

data : Object

Properties

element : element

The double-clicked element.
edit( evt )

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

evt : eventInfo

Properties

data : Object

Properties

dialog : String

Defaults to CKEDITOR.plugins.widget.definition.dialog and can be changed or set by the listener.
focus( evt )

An event fired when a widget is focused.

Widget can be focused by executing focus.

Parameters

evt : eventInfo
key( evt )

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

Properties

data : Object

Properties

keyCode : Number

A number representing the key code (or combination).
ready( evt )
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

evt : eventInfo
select( evt )

An event fired when a widget is selected.

Parameters

evt : eventInfo

CKEDITOR.plugins.widget

Filtering

Properties

allowedContent : allowedContentRulesCKEDITOR.plugins.widget#allowedContent

button : StringCKEDITOR.plugins.widget#button

contentForms : ObjectCKEDITOR.plugins.widget#contentForms

contentTransformations : ObjectCKEDITOR.plugins.widget#contentTransformations

data : ObjectCKEDITOR.plugins.widget#data

dataReady : BooleanCKEDITOR.plugins.widget#dataReady

defaults : ObjectCKEDITOR.plugins.widget#defaults

definition : definitionCKEDITOR.plugins.widget#definition

dialog : StringCKEDITOR.plugins.widget#dialog

downcast : String | FunctionCKEDITOR.plugins.widget#downcast

downcasts : ObjectCKEDITOR.plugins.widget#downcasts

draggable : BooleanCKEDITOR.plugins.widget#draggable

edit : FunctionCKEDITOR.plugins.widget#edit

editables : ObjectCKEDITOR.plugins.widget#editables

editor : editorCKEDITOR.plugins.widget#editor

element : elementCKEDITOR.plugins.widget#element

focusedEditable : nestedEditableCKEDITOR.plugins.widget#focusedEditable

getLabel : FunctionCKEDITOR.plugins.widget#getLabel

id : NumberCKEDITOR.plugins.widget#id

init : FunctionCKEDITOR.plugins.widget#init

inited : BooleanCKEDITOR.plugins.widget#inited

inline : BooleanCKEDITOR.plugins.widget#inline

insert : FunctionCKEDITOR.plugins.widget#insert

mask : BooleanCKEDITOR.plugins.widget#mask

name : StringCKEDITOR.plugins.widget#name

parts : ObjectCKEDITOR.plugins.widget#parts

pathName : StringCKEDITOR.plugins.widget#pathName

ready : BooleanCKEDITOR.plugins.widget#ready

repository : repositoryCKEDITOR.plugins.widget#repository

requiredContent : contentRuleCKEDITOR.plugins.widget#requiredContent

styleToAllowedContentRules : FunctionCKEDITOR.plugins.widget#styleToAllowedContentRules

styleableElements : StringCKEDITOR.plugins.widget#styleableElements

template : templateCKEDITOR.plugins.widget#template

upcast : String | FunctionCKEDITOR.plugins.widget#upcast

upcastPriority : NumberCKEDITOR.plugins.widget#upcastPriority

upcasts : ObjectCKEDITOR.plugins.widget#upcasts

wrapper : elementCKEDITOR.plugins.widget#wrapper

Static properties

WRAPPER_CLASS_PREFIX : StringCKEDITOR.plugins.widget#WRAPPER_CLASS_PREFIX

useCapture : BooleanCKEDITOR.plugins.widget#useCapture

Methods

constructor( widgetsRepo, id, element, widgetDef, [ startupData ] ) → widgetCKEDITOR.plugins.widget#constructor

Parameters

Returns

addClass( className )CKEDITOR.plugins.widget#addClass

Parameters

applyStyle( style )CKEDITOR.plugins.widget#applyStyle

Parameters

capture()CKEDITOR.plugins.widget#capture

checkStyleActive( style ) → BooleanCKEDITOR.plugins.widget#checkStyleActive

Parameters

Returns

define( name, meta )CKEDITOR.plugins.widget#define

Parameters

destroy( [ offline ] )CKEDITOR.plugins.widget#destroy

Parameters

destroyEditable( editableName, [ offline ] )CKEDITOR.plugins.widget#destroyEditable

Parameters

edit() → BooleanCKEDITOR.plugins.widget#edit

Returns

fire( eventName, [ data ], [ editor ] ) → Boolean | ObjectCKEDITOR.plugins.widget#fire

Parameters

Returns

fireOnce( eventName, [ data ], [ editor ] ) → Boolean | ObjectCKEDITOR.plugins.widget#fireOnce

Parameters

Returns

focus()CKEDITOR.plugins.widget#focus

getClasses() → ObjectCKEDITOR.plugins.widget#getClasses

Returns

hasClass( className, Whether )CKEDITOR.plugins.widget#hasClass

Parameters

hasListeners( eventName ) → BooleanCKEDITOR.plugins.widget#hasListeners

Parameters

Returns

initEditable( editableName, definition ) → BooleanCKEDITOR.plugins.widget#initEditable

Parameters

Returns

`allowedContent : allowedContentRules`

`button : String`

`contentForms : Object`

`contentTransformations : Object`

`data : Object`

`dataReady : Boolean`

`defaults : Object`

`definition : definition`

`dialog : String`

`downcast : String | Function`

`downcasts : Object`

`draggable : Boolean`

`edit : Function`

`editables : Object`

`editor : editor`

`element : element`

`focusedEditable : nestedEditable`

`getLabel : Function`

`id : Number`

`init : Function`

`inited : Boolean`

`inline : Boolean`

`insert : Function`

`mask : Boolean`

`name : String`

`parts : Object`

`pathName : String`

`ready : Boolean`

`repository : repository`

`requiredContent : contentRule`

`styleToAllowedContentRules : Function`

`styleableElements : String`

`template : template`

`upcast : String | Function`

`upcastPriority : Number`

`upcasts : Object`

`wrapper : element`

`WRAPPER_CLASS_PREFIX : String`

`useCapture : Boolean`

`constructor( widgetsRepo, id, element, widgetDef, [ startupData ] ) → widget`

`addClass( className )`

`applyStyle( style )`

`capture()`

`checkStyleActive( style ) → Boolean`

`define( name, meta )`

`destroy( [ offline ] )`

`destroyEditable( editableName, [ offline ] )`

`edit() → Boolean`

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

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

`focus()`

`getClasses() → Object`

`hasClass( className, Whether )`

`hasListeners( eventName ) → Boolean`

`initEditable( editableName, definition ) → Boolean`

`isInited() → Boolean`

`isReady() → Boolean`

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

`once()`

`removeAllListeners()`

`removeClass( className )`

`removeListener( eventName, listenerFunction )`

`removeStyle( style )`

`setData( keyOrData, value ) → widget`

`setFocused( selected ) → widget`

`setSelected( selected ) → widget`

`toFeature() → feature`

`updateDragHandlerPosition()`

`_findOneNotNested( selector ) → element`

`getNestedEditable( guard, node ) → element | null`

`isDomDragHandler( node ) → Boolean`

`isDomDragHandlerContainer( node ) → Boolean`

`isDomNestedEditable( node ) → Boolean`

`isDomWidget( node ) → Boolean`

`isDomWidgetElement( node ) → Boolean`

`isDomWidgetWrapper( node ) → Boolean`

`isParserWidgetElement( node ) → Boolean`

`isParserWidgetWrapper( node ) → Boolean`

`blur( evt )`

`contextMenu( evt )`