Report an issue
Class

CKEDITOR.plugins.widget

class since 4.3.0

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

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

  • inherited

    data : Function

    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

    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'
    }
    
  • readonly

    definition : definition

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

    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]'
        }
    }
    
  • readonly

    editor : editor

    The editor instance.

  • readonly

    element : element

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

  • readonly

    focusedEditable : nestedEditable

    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.

  • readonly

    id : Number

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

    inited : Boolean

    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

    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

    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:

    Parameters

    options : Object

    Options object added in 4.11.0.

  • mask : Boolean | String

    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

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

  • since 4.14.0 readonly

    partSelectors : Object

    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

    An object containing definitions of widget components (part name => CSS selector).

    parts: {
        image: 'img',
        caption: 'div.caption'
    }
    
  • pathName : String

    The widget name displayed in the elements path.

  • readonly

    ready : Boolean

    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

    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

  • since 4.4.0

    styleToAllowedContentRules : Function

    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

    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

    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

    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

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

    wrapper : 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.

Static properties

  • since 4.6.0 readonly static

    WRAPPER_CLASS_PREFIX : String

    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

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

    addClass( className )

    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 )

    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.

  • since 4.4.0

    checkStyleActive( style ) → Boolean

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

  • since 4.4.0

    getClasses() → 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.

    Returns

    Object
  • since 4.13.0 inherited

    getClipboardHtml() → String

    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 )

    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
    

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

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

    CKEDITOR.event.on

  • since 4.14.0

    refreshMask()

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

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

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

  • since 4.4.0

    removeClass( className )

    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.

  • since 4.4.0

    removeStyle( style )

    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

    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

    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

    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.

  • since 4.5.0 private

    _findOneNotNested( selector ) → element

    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

    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 )

    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

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

    Parameters

    node : node

    Returns

    Boolean
  • since 4.5.0 static

    isDomDragHandlerContainer( node ) → Boolean

    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

    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

    Checks whether the node is a DOM widget.

    Parameters

    node : node

    Returns

    Boolean
  • since 4.5.0 static

    isDomWidgetElement( node ) → Boolean

    Checks whether the node is a widget element.

    Parameters

    node : node

    Returns

    Boolean
  • since 4.5.0 static

    isDomWidgetWrapper( node ) → Boolean

    Checks whether the node is a widget wrapper.

    Parameters

    node : element

    Returns

    Boolean
  • since 4.5.0 static

    isParserWidgetElement( node ) → Boolean

    Checks whether the node is a widget element.

    Parameters

    node : node

    Returns

    Boolean
  • since 4.5.0 static

    isParserWidgetWrapper( node ) → Boolean

    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
  • 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
  • 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
  • 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
  • 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
  • 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