Home/CKEditor 4/API

CKEDITOR.plugins.widget

class since 4.3.0

Hierarchy

definition
- widget

Mixes

event
feature

See source

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

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

See source

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

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

See source
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
inherited
data : Function

See source
If set, it will be added as the CKEDITOR.plugins.widget.data event listener. This means that it will be executed every time the widget data changes.
readonly
dataReady : Boolean

See source
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
See source
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'
}
```
readonly
definition : definition

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

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

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

See source

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

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

See source
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
See source
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]'
    }
}
```
readonly
editor : editor

See source
The editor instance.
readonly
element : element

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

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

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

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

See source
If set to true/false, it will force the widget to be either an inline or a block widget. If not set, the widget type will be determined from the widget element.

Widget type influences whether a block (<div>) or an inline (<span>) element is used for the wrapper.
insert : Function
See source
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.
Parameters

options : Object

Options object added in 4.11.0.
mask : Boolean | String

See source
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 iframes that generate a separate "context".

If the value is a string type, then the partial mask covering only the given widget part is created instead. The string mask should point to the name of one of the widget parts.

Note: Partial mask is available since the 4.13.0 version.
inherited
name : String

See source
Widget definition name. It is automatically set when the definition is registered.
since 4.14.0 readonly
partSelectors : Object

See source
An object containing definitions of widget parts (part name => CSS selector).

Unlike the parts object, it stays unchanged throughout the widget lifecycle and is used in the refreshParts method.
inherited
parts : Object
See source
An object containing definitions of widget components (part name => CSS selector).
```
parts: {
    image: 'img',
    caption: 'div.caption'
}
```
pathName : String

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

See source
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
readonly
repository : repository

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

See source
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
since 4.4.0
styleToAllowedContentRules : Function
See source
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
            }
        };
    }
} );
```
Parameters

style : widget

The style to be transformed.
since 4.4.0
styleableElements : String
See source
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.
inherited
template : String

See source
The template which will be used to create a new widget element (when the widget's command is executed). This string is populated with default values by using the CKEDITOR.template format. Therefore it has to be a valid CKEDITOR.template argument.
upcast : String | Function
See source
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).
since 4.5.0
upcastPriority : Number

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

See source

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

readonly
wrapper : element

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

since 4.6.0 readonly static
WRAPPER_CLASS_PREFIX : String

See source
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_'
mixed static
useCapture : Boolean

See source

Methods

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

See source
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
since 4.4.0
addClass( className )

See source
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.
since 4.4.0
applyStyle( style )

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

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

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

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

Parameters

name : String

The event name

meta : Object
destroy( [ offline ] )

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

See source
Destroys a nested editable and all nested widgets.

Parameters

editableName : String

Nested editable name.

[ offline ] : Boolean

See destroy method.
edit() → Boolean

See source
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
See source
Fires an specific event in the object. All registered listeners are called at this point.
```
someObject.on( 'someEvent', function() { ... } );
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );             // Both listeners are called.

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

eventName : String

The event name to fire.

[ data ] : Object

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

[ editor ] : editor

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

Returns

Boolean | Object

A boolean indicating that the event is to be canceled, or data returned by one of the listeners.
fireOnce( eventName, [ data ], [ editor ] ) → Boolean | Object
See source
Fires an specific event in the object, releasing all listeners registered to that event. The same listeners are not called again on successive calls of it or of fire.
```
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );         // Above listener called.
someObject.fireOnce( 'someEvent' );     // Above listener called.
someObject.fire( 'someEvent' );         // No listeners called.
```
Parameters

eventName : String

The event name to fire.

[ data ] : Object

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

[ editor ] : editor

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

Returns

Boolean | Object

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

See source
Focuses a widget by selecting it.
since 4.4.0
getClasses() → Object

See source
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
since 4.13.0 inherited
getClipboardHtml() → String

See source
Customizes widget HTML copied to the clipboard during copy, cut and drop operations.

If not set, the current widget HTML will be used instead.

Note: This method will overwrite the HTML for the whole widget, including any nested widgets.

Returns

String

Widget HTML.
since 4.4.0
hasClass( className, Whether )

See source
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
See source
Checks if there is any listener registered to a given event.
```
var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
alert( someObject.hasListeners( 'someEvent' ) );    // true
alert( someObject.hasListeners( 'noEvent' ) );      // false
```
Parameters

eventName : String

The event name.

Returns

Boolean
initEditable( editableName, definition ) → Boolean

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

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

See inited for more details.

Returns

Boolean
isReady() → Boolean

See source
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
See source
Registers a listener to a specific event in the current object.
```
someObject.on( 'someEvent', function() {
    alert( this == someObject );        // true
} );

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

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

someObject.on( 'someEvent', function() { ... } );                       // 2nd called
someObject.on( 'someEvent', function() { ... }, null, null, 100 );      // 3rd called
someObject.on( 'someEvent', function() { ... }, null, null, 1 );        // 1st called
```
Note: CKEditor's event system has a limitation that one function cannot be used as a listener for the same event more than once. Hence, to reuse it with multiple listeners, it should be wrapped into additional wrapper function:
```
function listener( evt ) { ... };

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

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

eventName : String

The event name to which listen.

listenerFunction : Function

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

[ scopeObj ] : Object

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

[ listenerData ] : Object

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

[ priority ] : Number

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

Defaults to 10

Returns

Object

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

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

CKEDITOR.event.on
since 4.14.0
refreshMask()

See source
Refreshes the widget's mask. It can be used together with the refreshParts method to reinitialize the mask for dynamically created widgets.
since 4.14.0
refreshParts( [ refreshInitialized ] )

See source
Reinitializes the widget's parts.

This method can be used to link new DOM elements to widget parts, for example in case when the widget's HTML is created asynchronously or modified during the widget lifecycle. Note that it uses the partSelectors object, so it does not refresh parts that were created manually.

Parameters

[ refreshInitialized ] : Boolean

Whether the parts that are already initialized should be reinitialized.

Defaults to true
removeAllListeners()

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

See source
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 )
See source
Unregisters a listener function from being called at the specified event. No errors are thrown if the listener has not been registered previously.
```
var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener called.
someObject.removeListener( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener not called.
```
Parameters

eventName : String

The event name.

listenerFunction : Function

The listener function to unregister.
since 4.4.0
removeStyle( style )

See source
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.
chainable
setData( keyOrData, value ) → widget
See source
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
chainable
setFocused( selected ) → widget

See source
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
chainable
setSelected( selected ) → widget

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

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

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

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

since 4.5.0 static
getNestedEditable( guard, node ) → element | null

See source
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.
mixed static
implementOn( targetObject )
See source
Implements the CKEDITOR.event features in an object.
```
var myObject = { message: 'Example' };
CKEDITOR.event.implementOn( myObject );

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

targetObject : Object

The object into which implement the features.
since 4.5.0 static
isDomDragHandler( node ) → Boolean

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

Parameters

node : node

Returns

Boolean
since 4.5.0 static
isDomDragHandlerContainer( node ) → Boolean

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

Parameters

node : node

Returns

Boolean
since 4.5.0 static
isDomNestedEditable( node ) → Boolean

See source
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
since 4.8.0 static
isDomWidget( node ) → Boolean

See source
Checks whether the node is a DOM widget.

Parameters

node : node

Returns

Boolean
since 4.5.0 static
isDomWidgetElement( node ) → Boolean

See source
Checks whether the node is a widget element.

Parameters

node : node

Returns

Boolean
since 4.5.0 static
isDomWidgetWrapper( node ) → Boolean

See source
Checks whether the node is a widget wrapper.

Parameters

node : element

Returns

Boolean
since 4.5.0 static
isParserWidgetElement( node ) → Boolean

See source
Checks whether the node is a widget element.

Parameters

node : node

Returns

Boolean
since 4.5.0 static
isParserWidgetWrapper( node ) → Boolean

See source
Checks whether the node is a widget wrapper.

Parameters

node : element

Returns

Boolean

Events

blur( evt )

See source
An event fired when a widget is blurred.

Parameters

evt : eventInfo
contextMenu( evt )

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

Parameters

evt : eventInfo
deselect( evt )

See source
An event fired when a widget is deselected.

Parameters

evt : eventInfo
destroy( evt )

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

Parameters

evt : eventInfo
dialog( evt )

See source
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
doubleclick( evt )
See source
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
edit( evt )

See source
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
focus( evt )

See source
An event fired when a widget is focused.

Widget can be focused by executing focus.

Parameters

evt : eventInfo
key( evt )

See source
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
ready( evt )
See source
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 )

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

inherited data : FunctionCKEDITOR.plugins.widget#data

readonly dataReady : BooleanCKEDITOR.plugins.widget#dataReady

defaults : ObjectCKEDITOR.plugins.widget#defaults

readonly 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

readonly editor : editorCKEDITOR.plugins.widget#editor

readonly element : elementCKEDITOR.plugins.widget#element

readonly focusedEditable : nestedEditableCKEDITOR.plugins.widget#focusedEditable

getLabel : FunctionCKEDITOR.plugins.widget#getLabel

readonly id : NumberCKEDITOR.plugins.widget#id

init : FunctionCKEDITOR.plugins.widget#init

readonly inited : BooleanCKEDITOR.plugins.widget#inited

inherited inline : BooleanCKEDITOR.plugins.widget#inline

insert : FunctionCKEDITOR.plugins.widget#insert

Parameters

mask : Boolean | StringCKEDITOR.plugins.widget#mask

inherited name : StringCKEDITOR.plugins.widget#name

since 4.14.0 readonly partSelectors : ObjectCKEDITOR.plugins.widget#partSelectors

inherited parts : ObjectCKEDITOR.plugins.widget#parts

pathName : StringCKEDITOR.plugins.widget#pathName

readonly ready : BooleanCKEDITOR.plugins.widget#ready

readonly repository : repositoryCKEDITOR.plugins.widget#repository

requiredContent : contentRuleCKEDITOR.plugins.widget#requiredContent

since 4.4.0 styleToAllowedContentRules : FunctionCKEDITOR.plugins.widget#styleToAllowedContentRules

Parameters

since 4.4.0 styleableElements : StringCKEDITOR.plugins.widget#styleableElements

inherited template : StringCKEDITOR.plugins.widget#template

upcast : String | FunctionCKEDITOR.plugins.widget#upcast

since 4.5.0 upcastPriority : NumberCKEDITOR.plugins.widget#upcastPriority

upcasts : ObjectCKEDITOR.plugins.widget#upcasts

readonly wrapper : elementCKEDITOR.plugins.widget#wrapper

Static properties

since 4.6.0 readonly static WRAPPER_CLASS_PREFIX : StringCKEDITOR.plugins.widget#WRAPPER_CLASS_PREFIX

mixed static useCapture : BooleanCKEDITOR.plugins.widget#useCapture

Methods

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

Parameters

Returns

since 4.4.0 addClass( className )CKEDITOR.plugins.widget#addClass

Parameters

since 4.4.0 applyStyle( style )CKEDITOR.plugins.widget#applyStyle

Parameters

capture()CKEDITOR.plugins.widget#capture

since 4.4.0 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

since 4.4.0 getClasses() → ObjectCKEDITOR.plugins.widget#getClasses

Returns

since 4.13.0 inherited getClipboardHtml() → StringCKEDITOR.plugins.widget#getClipboardHtml

Returns

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

Parameters

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

`allowedContent : allowedContentRules`

`button : String`

`contentForms : Object`

`contentTransformations : Object`

inherited
`data : Function`

readonly
`dataReady : Boolean`

`defaults : Object`

readonly
`definition : definition`

`dialog : String`

`downcast : String | Function`

`downcasts : Object`

`draggable : Boolean`

`edit : Function`

`editables : Object`

readonly
`editor : editor`

readonly
`element : element`

readonly
`focusedEditable : nestedEditable`

`getLabel : Function`

readonly
`id : Number`

`init : Function`

readonly
`inited : Boolean`

inherited
`inline : Boolean`

`insert : Function`

`mask : Boolean | String`

inherited
`name : String`

since 4.14.0 readonly
`partSelectors : Object`

inherited
`parts : Object`

`pathName : String`

readonly
`ready : Boolean`

readonly
`repository : repository`

`requiredContent : contentRule`

since 4.4.0
`styleToAllowedContentRules : Function`

since 4.4.0
`styleableElements : String`

inherited
`template : String`

`upcast : String | Function`

since 4.5.0
`upcastPriority : Number`

`upcasts : Object`

readonly
`wrapper : element`

since 4.6.0 readonly static
`WRAPPER_CLASS_PREFIX : String`

mixed static
`useCapture : Boolean`

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

since 4.4.0
`addClass( className )`

since 4.4.0
`applyStyle( style )`

`capture()`

since 4.4.0
`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()`

since 4.4.0
`getClasses() → Object`

since 4.13.0 inherited
`getClipboardHtml() → String`

since 4.4.0
`hasClass( className, Whether )`

`hasListeners( eventName ) → Boolean`

`initEditable( editableName, definition ) → Boolean`

`isInited() → Boolean`

`isReady() → Boolean`

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

`once()`

since 4.14.0
`refreshMask()`

since 4.14.0
`refreshParts( [ refreshInitialized ] )`

`removeAllListeners()`

since 4.4.0
`removeClass( className )`

`removeListener( eventName, listenerFunction )`

since 4.4.0
`removeStyle( style )`

chainable
`setData( keyOrData, value ) → widget`

chainable
`setFocused( selected ) → widget`

chainable
`setSelected( selected ) → widget`

`toFeature() → feature`

`updateDragHandlerPosition()`

since 4.5.0 private
`_findOneNotNested( selector ) → element`

since 4.5.0 static
`getNestedEditable( guard, node ) → element | null`

mixed static
`implementOn( targetObject )`

since 4.5.0 static
`isDomDragHandler( node ) → Boolean`

since 4.5.0 static
`isDomDragHandlerContainer( node ) → Boolean`

since 4.5.0 static
`isDomNestedEditable( node ) → Boolean`

since 4.8.0 static
`isDomWidget( node ) → Boolean`

since 4.5.0 static
`isDomWidgetElement( node ) → Boolean`