CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 4/API
Class

CKEDITOR.editor

class
See source

Represents an editor instance. This constructor should be rarely used in favor of the CKEDITOR editor creation functions.

Filtering

Properties

  • since 4.3.0 readonly

    activeEnterMode : Number

    See source

    The dynamic Enter mode which should be used in the current context (selection location). By default it equals the enterMode and it can be changed by the setActiveEnterMode method.

    See also the setActiveEnterMode method for an explanation of dynamic settings.

  • since 4.3.0 readonly

    activeFilter : filter

    See source

    The active filter instance which should be used in the current context (location selection). This instance will be used to make a decision which commands, buttons and other features can be enabled.

    By default it equals the filter and it can be changed by the setActiveFilter method.

    editor.on( 'activeFilterChange', function() {
    if ( editor.activeFilter.check( 'cite' ) )
        // Do something when <cite> was enabled - e.g. enable a button.
    else
        // Otherwise do something else.
} );

    See also the setActiveEnterMode method for an explanation of dynamic settings.

  • since 4.3.0 readonly

    activeShiftEnterMode : Number

    See source

    See the activeEnterMode property.

  • since 4.19.0 readonly

    applicationTitle : String | Boolean

    See source

    Indicates the human-readable title of this editor's application (the website's region that contains the editor and its whole UI). Although this is a read-only property, it can be initialized with CKEDITOR.config.applicationTitle.

    Note: Please do not confuse this property with editor.name which identifies the literal instance in the CKEDITOR.instances.

  • since 4.8.0 readonly

    balloonToolbars : contextManager

    See source

    The balloon toolbar manager for a given editor instance. It ensures that there is only one toolbar visible at a time.

    Use the CKEDITOR.plugins.balloontoolbar.contextManager.create method to register a new toolbar context.

    The following example will add a toolbar containing Link and Unlink buttons for any anchor or image:

    editor.balloonToolbars.create( {
    buttons: 'Link,Unlink',
    cssSelector: 'a[href], img'
} );

  • readonly

    blockless : Boolean

    See source

    Indicates that the editor is running in an environment where no block elements are accepted inside the content.

    This can be for example inline editor based on an <h1> element.

  • readonly

    config : config

    See source

    The configuration for this editor instance. It inherits all settings defined in CKEDITOR.config, combined with settings loaded from custom configuration files and those defined inline in the page when creating the editor.

    var editor = CKEDITOR.instances.editor1;
alert( editor.config.skin ); // e.g. 'moono'

  • readonly

    container : element

    See source

    The outermost element in the DOM tree in which the editable element resides. It is provided by a specific editor creator after the editor UI is created and is not intended to be modified.

    var editor = CKEDITOR.instances.editor1;
alert( editor.container.getName() ); // 'span'

  • readonly

    contextMenu : contextMenu

    See source

  • since 4.6.0

    copyFormatting : state

    See source

    Current state of the Copy Formatting plugin in this editor instance.

  • dataProcessor : dataProcessor

    See source

    If defined, points to the data processor which is responsible for translating and transforming the editor data on input and output. Generally it will point to an instance of CKEDITOR.htmlDataProcessor, which handles HTML data. The editor may also handle other data formats by using different data processors provided by specific plugins.

  • readonly

    document : document

    See source

    The document that stores the editor content.

    • For the classic (iframe-based) editor it is equal to the document inside the iframe containing the editable element.
    • For the inline editor it is equal to CKEDITOR.document.

    The document object is available after the contentDom event is fired and may be invalidated when the contentDomUnload event is fired (classic editor only).

    editor.on( 'contentDom', function() {
    console.log( editor.document );
} );

  • readonly

    element : element

    See source

    The original host page element upon which the editor is created. It is only supposed to be provided by the particular editor creator and is not subject to be modified.

  • readonly

    elementMode : Number

    See source

    This property indicates the way this instance is associated with the element. See also CKEDITOR.ELEMENT_MODE_INLINE and CKEDITOR.ELEMENT_MODE_REPLACE.

  • since 4.3.0 readonly

    enterMode : Number

    See source

    The main (static) Enter mode which is a validated version of the CKEDITOR.config.enterMode setting. Currently only one rule exists — blockless editors may have Enter modes set only to CKEDITOR.ENTER_BR.

  • since 4.1.0 readonly

    filter : filter

    See source

    The main filter instance used for input data filtering, data transformations, and activation of features.

    It points to a CKEDITOR.filter instance set up based on editor configuration.

  • readonly

    focusManager : focusManager

    See source

    Controls the focus state of this editor instance. This property is rarely used for normal API operations. It is mainly targeted at developers adding UI elements to the editor interface.

  • readonly

    id : String

    See source

    A unique random string assigned to each editor instance on the page.

  • readonly

    keystrokeHandler : keystrokeHandler

    See source

    Controls keystroke typing in this editor instance.

  • readonly

    lang : Object

    See source

    An object that contains all language strings used by the editor interface.

    alert( editor.lang.basicstyles.bold ); // e.g. 'Negrito' (if the language is set to Portuguese)

  • readonly

    langCode : String

    See source

    The code for the language resources that have been loaded for the user interface elements of this editor instance.

    alert( editor.langCode ); // e.g. 'en'

  • readonly

    mode : String

    See source

    The current editing mode. An editing mode basically provides different ways of editing or viewing the editor content.

    alert( CKEDITOR.instances.editor1.mode ); // (e.g.) 'wysiwyg'

  • readonly

    name : String

    See source

    A unique identifier of this editor instance.

    Note: It will be originated from the id or name attribute of the element, otherwise a name pattern of 'editor{n}' will be used.

  • since 4.5.0 readonly

    pasteFilter : filter

    See source

    Content filter which is used when external data is pasted or dropped into the editor or a forced paste as plain text occurs.

    This object might be used on the fly to define rules for pasted external content. This object is available and used if the clipboard plugin is enabled and CKEDITOR.config.pasteFilter or CKEDITOR.config.forcePasteAsPlainText was defined.

    To enable the filter:

    var editor = CKEDITOR.replace( 'editor', {
    pasteFilter: 'plain-text'
} );

    You can also modify the filter on the fly later on:

    editor.pasteFilter = new CKEDITOR.filter( 'p h1 h2; a[!href]' );

    Note that the paste filter is only applied to external data. There are three data sources:

    • copied and pasted in the same editor (internal),
    • copied from one editor and pasted into another (cross-editor),
    • coming from all other sources like websites, MS Word, etc. (external).

    If Advanced Content Filter is not disabled, then it will also be applied to pasted and dropped data. The paste filter job is to "normalize" external data which often needs to be handled differently than content produced by the editor.

  • readonly

    plugins : plugins

    See source

    An object that contains references to all plugins used by this editor instance.

    alert( editor.plugins.dialog.path ); // e.g. 'http://example.com/ckeditor/plugins/dialog/'

// Check if a plugin is available.
if ( editor.plugins.image ) {
    ...
}

  • since 3.6.0 readonly

    readOnly : Boolean

    See source

    Indicates the read-only state of this editor. This is a read-only property. See also setReadOnly.

  • since 4.3.0 readonly

    shiftEnterMode : Number

    See source

    See the enterMode property.

  • since 4.1.0 readonly

    status : String

    See source

    Indicates editor initialization status. The following statuses are available:

    • unloaded: The initial state — the editor instance was initialized, but its components (configuration, plugins, language files) are not loaded yet.
    • loaded: The editor components were loaded — see the loaded event.
    • recreating: The editor editable area is recreating due to iframe reloading — see the CKEDITOR.config.observableParent configuration option.
    • ready: The editor is fully initialized and ready — see the instanceReady event.
    • destroyed: The editor was destroyed — see the destroy method.

    Defaults to 'unloaded'

  • readonly

    tabIndex : Number

    See source

    The tabbing navigation order determined for this editor instance. This can be set by the CKEDITOR.config.tabIndex setting or taken from the tabindex attribute of the element associated with the editor.

    alert( editor.tabIndex ); // e.g. 0

    Defaults to 0

  • readonly

    templates : Object

    See source

    Contains all UI templates created for this editor instance.

    Defaults to {}

  • since 4.2.0 readonly

    title : String | Boolean

    See source

    Indicates the human-readable title of this editor. Although this is a read-only property, it can be initialized with CKEDITOR.config.title.

    Note: Please do not confuse this property with editor.name which identifies the instance in the CKEDITOR.instances literal.

  • readonly

    toolbar : Object

    See source

    The toolbar definition used by the editor. It is created from the CKEDITOR.config.toolbar option if it is set or automatically based on CKEDITOR.config.toolbarGroups.

  • readonly

    ui : ui

    See source

    The namespace containing UI features related to this editor instance.

  • since 4.5.0 readonly

    uploadRepository : uploadRepository

    See source

    An instance of the upload repository. It allows you to create and get file loaders.

    var loader = editor.uploadRepository.create( file );
loader.loadAndUpload( 'http://foo/bar' );

  • since 4.3.0 readonly

    widgets : repository

    See source

    An instance of widget repository. It contains all registered widget definitions and initialized instances.

    editor.widgets.add( 'someName', {
    // Widget definition...
} );

editor.widgets.registered.someName; // -> Widget definition

  • readonly

    window : window

    See source

    The window instance related to the document property.

    It is always equal to the editor.document.getWindow().

    See the document property documentation.

Static properties

Methods

  • constructor( [ instanceConfig ], [ element ], [ mode ] ) → editor

    See source

    Creates an editor class instance.

    Parameters

    [ instanceConfig ] : Object

    Configuration values for this specific instance.

    [ element ] : element

    The DOM element upon which this editor will be created.

    [ mode ] : Number

    The element creation mode to be used by this editor.

    Returns

    editor

  • addCommand( commandName, commandDefinition )

    See source

    Adds a command definition to the editor instance. Commands added with this function can be executed later with the execCommand method.

        editorInstance.addCommand( 'sample', {
        exec: function( editor ) {
            alert( 'Executing a command for the editor name "' + editor.name + '"!' );
        }
    } );

    Since 4.10.0 this method also accepts a CKEDITOR.command instance as a parameter.

    Parameters

    commandName : String

    The indentifier name of the command.

    commandDefinition : commandDefinition | command

    The command definition or a CKEDITOR.command instance.

  • since 4.4.0

    addContentsCss( cssPath )

    See source

    Adds the path to a stylesheet file to the exisiting CKEDITOR.config.contentsCss value.

    Note: This method is available only with the wysiwygarea plugin and only affects classic editors based on it (so it does not affect inline editors).

    editor.addContentsCss( 'assets/contents.css' );

    Parameters

    cssPath : String

    The path to the stylesheet file which should be added.

  • since 4.1.0

    addFeature( feature ) → Boolean

    See source

    Shorthand for CKEDITOR.filter.addFeature.

    Parameters

    feature : feature

    See CKEDITOR.filter.addFeature.

    Returns

    Boolean

    See CKEDITOR.filter.addFeature.

  • addMenuGroup( name, [ order ] )

    See source

    Registers an item group to the editor context menu in order to make it possible to associate it with menu items later.

    Parameters

    name : String

    Specify a group name.

    [ order ] : Number

    Define the display sequence of this group inside the menu. A smaller value gets displayed first.

    Defaults to 100

  • addMenuItem( name, definition )

    See source

    Adds an item from the specified definition to the editor context menu.

    Parameters

    name : String

    The menu item name.

    definition : Object

    The menu item definition.

  • addMenuItems( definitions )

    See source

    Adds one or more items from the specified definition object to the editor context menu.

    Parameters

    definitions : Object

    Object where keys are used as itemName and corresponding values as definition for a addMenuItem call.

  • addMode( mode, exec )

    See source

    Registers an editing mode. This function is to be used mainly by plugins.

    Parameters

    mode : String

    The mode name.

    exec : Function

    The function that performs the actual mode change.

  • since 3.3.0

    addRemoveFormatFilter( func )

    See source

    Add to a collection of functions to decide whether a specific element should be considered as formatting element and thus could be removed during removeFormat command.

    Note: Only available with the existence of removeformat plugin.

    // Don't remove empty span.
editor.addRemoveFormatFilter( function( element ) {
    return !( element.is( 'span' ) && CKEDITOR.tools.isEmpty( element.getAttributes() ) );
} );

    Parameters

    func : Function

    The function to be called, which will be passed an element to test.

  • applyStyle( style )

    See source

    Applies the style upon the editor's current selection. Shorthand for CKEDITOR.style.apply.

    Parameters

    style : style

  • attachStyleStateChange( style, callback )

    See source

    Registers a function to be called whenever the selection position changes in the editing area. The current state is passed to the function. The possible states are CKEDITOR.TRISTATE_ON and CKEDITOR.TRISTATE_OFF.

    // Create a style object for the <b> element.
var style = new CKEDITOR.style( { element: 'b' } );
var editor = CKEDITOR.instances.editor1;
editor.attachStyleStateChange( style, function( state ) {
    if ( state == CKEDITOR.TRISTATE_ON )
        alert( 'The current state for the B element is ON' );
    else
        alert( 'The current state for the B element is OFF' );
} );

    Parameters

    style : style

    The style to be watched.

    callback : Function

    The function to be called.

  • capture()

    See source

    Register event handler under the capturing stage on supported target.

  • checkDirty() → Boolean

    See source

    Checks whether the current editor content contains changes when compared to the content loaded into the editor at startup, or to the content available in the editor when resetDirty was called.

    function beforeUnload( evt ) {
    if ( CKEDITOR.instances.editor1.checkDirty() )
        return evt.returnValue = "You will lose the changes made in the editor.";
}

if ( window.addEventListener )
    window.addEventListener( 'beforeunload', beforeUnload, false );
else
    window.attachEvent( 'onbeforeunload', beforeUnload );

    Returns

    Boolean

    true if the content contains changes.

  • createFakeElement( realElement, className, realElementType, isResizable ) → element

    See source

    Creates fake CKEDITOR.dom.element based on real element. Fake element is an img with special attributes, which keep real element properties.

    Parameters

    realElement : element

    Real element to transform.

    className : String

    Class name which will be used as class of fake element.

    realElementType : String

    Stores type of fake element.

    isResizable : Boolean

    Keeps information if element is resizable.

    Returns

    element

    Fake element.

  • createFakeParserElement( realElement, className, realElementType, isResizable ) → element

    See source

    Creates fake CKEDITOR.htmlParser.element based on real element.

    Parameters

    realElement : element

    Real element to transform.

    className : String

    Class name which will be used as class of fake element.

    realElementType : String

    Store type of fake element.

    isResizable : Boolean

    Keep information if element is resizable.

    Returns

    element

    Fake htmlParser element.

  • createRange() → range

    See source

    Shortcut to create a CKEDITOR.dom.range instance from the editable element.

    Returns

    range

    The DOM range created if the editable has presented. CKEDITOR.dom.range

  • define( name, meta )

    See source

    Predefine some intrinsic properties on a specific event name.

    Parameters

    name : String

    The event name

    meta : Object

  • destroy( [ noUpdate ] )

    See source

    Destroys the editor instance, releasing all resources used by it. If the editor replaced an element, the element will be recovered.

    alert( CKEDITOR.instances.editor1 ); // e.g. object
CKEDITOR.instances.editor1.destroy();
alert( CKEDITOR.instances.editor1 ); // undefined

    Parameters

    [ noUpdate ] : Boolean

    If the instance is replacing a DOM element, this parameter indicates whether or not to update the element with the instance content.

  • editable( [ elementOrEditable ] ) → element | null

    See source

    Creates, retrieves or detaches an editable element of the editor. This method should always be used instead of calling CKEDITOR.editable directly.

    Parameters

    [ elementOrEditable ] : element | editable

    The DOM element to become the editable or a CKEDITOR.editable object.

    Returns

    element | null

    The editor's editable element, or null if not available.

  • elementPath( [ startNode ] ) → elementPath

    See source

    Returns an element path for the selection in the editor.

    Parameters

    [ startNode ] : node

    From which the path should start, if not specified defaults to editor selection's start element yielded by CKEDITOR.dom.selection.getStartElement.

    Returns

    elementPath

  • execCommand( commandName, [ data ] ) → Boolean

    See source

    Executes a command associated with the editor.

    editorInstance.execCommand( 'bold' );

    Parameters

    commandName : String

    The identifier name of the command.

    [ data ] : Object

    The data to be passed to the command. It defaults to an empty object starting from 4.7.0.

    Returns

    Boolean

    true if the command was executed successfully, false otherwise. CKEDITOR.editor.addCommand

  • since 4.5.0

    extractSelectedHtml( [ toString ], [ removeEmptyBlock ] ) → documentFragment | String | null

    See source

    Gets the selected HTML (it is returned as a document fragment or a string) and removes the selected part of the DOM. This method is designed to work as the user would expect the cut and delete functionalities to work.

    See also:

    Parameters

    [ toString ] : Boolean

    If true, then stringified HTML will be returned.

    [ removeEmptyBlock ] : Boolean

    Default false means that the function will keep an empty block (if the entire content was removed) or it will create it (if a block element was removed) and set the selection in that block. If true, the empty block will be removed or not created. In this case the function will not handle the selection.

    Defaults to false

    Returns

    documentFragment | String | null

  • 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

    Moves the selection focus to the editing area space in the editor.

  • forceNextSelectionCheck()

    See source

  • getClipboardData( callbackOrOptions, callback )

    See source

    Gets clipboard data by directly accessing the clipboard (IE only) or opening the paste dialog window.

    editor.getClipboardData( function( data ) {
    if ( data )
        alert( data.type + ' ' + data.dataValue );
} );

    Parameters

    callbackOrOptions : Function | Object

    For function, see the callback parameter documentation. The object was used before 4.7.0 with the title property, to set the paste dialog's title.

    callback : Function

    A function that will be executed with the data property of the paste event or null if none of the capturing methods succeeded. Since 4.7.0 the callback should be provided as a first argument, just like in the example above. This parameter will be removed in an upcoming major release.

  • getColorFromDialog( callback, [ scope ] )

    See source

    Open up color dialog and to receive the selected color.

    Parameters

    callback : Function

    The callback when color dialog is closed

    [ scope ] : Object

    The scope in which the callback will be bound.

  • getCommand( commandName ) → command

    See source

    Gets one of the registered commands. Note that after registering a command definition with addCommand, it is transformed internally into an instance of CKEDITOR.command, which will then be returned by this function.

    Parameters

    commandName : String

    The name of the command to be returned. This is the same name that is used to register the command with addCommand.

    Returns

    command

    The command object identified by the provided name.

  • since 4.6.0

    getCommandKeystroke( command, [ all ] ) → Number | Number[] | null

    See source

    Returns the keystroke that is assigned to a specified CKEDITOR.command. If no keystroke is assigned, it returns null.

    Since version 4.7.0 this function also accepts a command parameter as a string.

    Parameters

    command : command | String

    The CKEDITOR.command instance or a string with the command name.

    [ all ] : Boolean

    If true, the function will return an array of assigned keystrokes. Available since 4.11.0.

    Defaults to false

    Returns

    Number | Number[] | null

    Depending on the all parameter value:

    • false – The first keystroke assigned to the provided command or null if there is no keystroke.
    • true – An array of all assigned keystrokes or an empty array if there is no keystroke.

  • getData( internal ) → String

    See source

    Gets the editor data. The data will be in "raw" format. It is the same data that is posted by the editor.

    if ( CKEDITOR.instances.editor1.getData() == '' )
    alert( 'There is no data available.' );

    Parameters

    internal : Boolean

    If set to true, it will prevent firing the beforeGetData and getData events, so the real content of the editor will not be read and cached data will be returned. The method will work much faster, but this may result in the editor returning the data that is not up to date. This parameter should thus only be set to true when you are certain that the cached data is up to date.

    Returns

    String

    The editor data.

  • getMenuItem( name ) → Object

    See source

    Retrieves a particular menu item definition from the editor context menu.

    Parameters

    name : String

    The name of the desired menu item.

    Returns

    Object

  • getResizable( forContents ) → element

    See source

    Gets the element that can be used to check the editor size. This method is mainly used by the Editor Resize plugin, which adds a UI handle that can be used to resize the editor.

    Parameters

    forContents : Boolean

    Whether to return the "contents" part of the theme instead of the container.

    Returns

    element

    The resizable element.

  • since 4.5.0

    getSelectedHtml( [ toString ] ) → documentFragment | String

    See source

    Gets the selected HTML (it is returned as a document fragment or a string). This method is designed to work as the user would expect the copy functionality to work. For instance, if the following selection was made:

    <p>a<b>b{c}d</b>e</p>

    The following HTML will be returned:

    <b>c</b>

    As you can see, the information about the bold formatting was preserved, even though the selection was anchored inside the <b> element.

    See also:

    Parameters

    [ toString ] : Boolean

    If true, then stringified HTML will be returned.

    Returns

    documentFragment | String

  • since 4.14.0

    getSelectedRanges( [ onlyEditables ] ) → Array

    See source

    Retrieves the CKEDITOR.dom.range instances that represent the current selection.

    Note: This function is an alias for the CKEDITOR.dom.selection.getRanges method.

    Parameters

    [ onlyEditables ] : Boolean

    If set to true, this function retrieves editable ranges only.

    Returns

    Array

    Range instances that represent the current selection.

  • getSelection( forceRealSelection ) → selection | null

    See source

    Retrieve the editor selection in scope of editable element.

    Note: Since the native browser selection provides only one single selection at a time per document, so if editor's editable element has lost focus, this method will return a null value unless the lockSelection has been called beforehand so the saved selection is retrieved.

    var selection = CKEDITOR.instances.editor1.getSelection();
alert( selection.getType() );

    Parameters

    forceRealSelection : Boolean

    Return real selection, instead of saved or fake one.

    Returns

    selection | null

    A selection object or null if not available for the moment.

  • getSnapshot() → String

    See source

    Gets the "raw data" currently available in the editor. This is a fast method which returns the data as is, without processing, so it is not recommended to use it on resulting pages. Instead it can be used combined with the loadSnapshot method in order to automatically save the editor data from time to time while the user is using the editor, to avoid data loss, without risking performance issues.

    alert( editor.getSnapshot() );

    See also:

    Returns

    String

    Editor "raw data".

  • getStylesSet( callback )

    See source

    Gets the current stylesSet for this instance.

    editor.getStylesSet( function( stylesDefinitions ) {} );

    See also stylesSet event.

    Parameters

    callback : Function

    The function to be called with the styles data.

  • getUiColor() → String

    See source

    Gets the color of the editor user interface.

    CKEDITOR.instances.editor1.getUiColor();

    Returns

    String

    uiColor The editor UI color or undefined if the UI color is not set.

  • 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

  • insertElement( element )

    See source

    Inserts an element into the currently selected position in the editor in WYSIWYG mode.

    var element = CKEDITOR.dom.element.createFromHtml( '<img src="hello.png" border="0" title="Hello" />' );
CKEDITOR.instances.editor1.insertElement( element );

    Fires the insertElement event. The element is inserted in the listener with a default priority (10), so you can add listeners with lower or higher priorities in order to execute some code before or after the element is inserted.

    Parameters

    element : element

    The element to be inserted into the editor.

  • insertHtml( html, [ mode ], [ range ] )

    See source

    Inserts HTML code into the currently selected position in the editor in WYSIWYG mode.

    Example:

    CKEDITOR.instances.editor1.insertHtml( '<p>This is a new paragraph.</p>' );

    Fires the insertHtml and afterInsertHtml events. The HTML is inserted in the insertHtml event's listener with a default priority (10) so you can add listeners with lower or higher priorities in order to execute some code before or after the HTML is inserted.

    Parameters

    html : String

    HTML code to be inserted into the editor.

    [ mode ] : String

    The mode in which the HTML code will be inserted. One of the following:

    • 'html' – The inserted content will completely override the styles at the selected position.
    • 'unfiltered_html' – Like 'html' but the content is not filtered with CKEDITOR.filter.
    • 'text' – The inserted content will inherit the styles applied in the selected position. This mode should be used when inserting "htmlified" plain text (HTML without inline styles and styling elements like <b>, <strong>, <span style="...">).

    Defaults to 'html'

    [ range ] : range

    If specified, the HTML will be inserted into the range instead of into the selection. The selection will be placed at the end of the insertion (like in the normal case). Introduced in CKEditor 4.5.

  • since 3.5.0

    insertText( text )

    See source

    Inserts text content into the currently selected position in the editor in WYSIWYG mode. The styles of the selected element will be applied to the inserted text. Spaces around the text will be left untouched.

    CKEDITOR.instances.editor1.insertText( ' line1 \n\n line2' );

    Fires the insertText and afterInsertHtml events. The text is inserted in the insertText event's listener with a default priority (10) so you can add listeners with lower or higher priorities in order to execute some code before or after the text is inserted.

    Parameters

    text : String

    Text to be inserted into the editor.

  • since 4.13.0

    isDestroyed() → Boolean

    See source

    Determines if the current editor instance is destroyed.

    Returns

    Boolean

    true if the editor is destroyed.

  • since 4.13.0

    isDetached() → Boolean

    See source

    Provides information whether the editor's container is detached.

    Returns

    Boolean

    true if the editor's container is detached.

  • loadSnapshot( snapshot )

    See source

    Loads "raw data" into the editor. The data is loaded with processing straight to the editing area. It should not be used as a way to load any kind of data, but instead in combination with getSnapshot-produced data.

    var data = editor.getSnapshot();
editor.loadSnapshot( data );

    CKEDITOR.editor.setData

    Parameters

    snapshot : Object

  • lockSelection( [ sel ] ) → Boolean

    See source

    Locks the selection made in the editor in order to make it possible to manipulate it without browser interference. A locked selection is cached and remains unchanged until it is released with the unlockSelection method.

    Parameters

    [ sel ] : selection

    Specify the selection to be locked.

    Returns

    Boolean

    true if selection was locked.

  • 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

  • openDialog( dialogName, callback, [ forceModel ] ) → dialog

    See source

    Loads and opens a registered dialog.

    CKEDITOR.instances.editor1.openDialog( 'smiley' );

    Parameters

    dialogName : String

    The registered name of the dialog.

    callback : Function

    The function to be invoked after a dialog instance is created.

    [ forceModel ] : element | widget | Object

    Forces opening the dialog using the given model as a subject. The forced model will take precedence before the CKEDITOR.dialog.definition.getModel method. Available since 4.13.0.

    Returns

    dialog

    The dialog object corresponding to the dialog displayed or null if the dialog name is not registered. CKEDITOR.dialog.add

  • popup( url, [ width ], [ height ], [ options ] )

    See source

    Opens Browser in a popup. The width and height parameters accept numbers (pixels) or percent (of screen size) values.

    Parameters

    url : String

    The url of the external file browser.

    [ width ] : Number | String

    Popup window width.

    Defaults to '80%'

    [ height ] : Number | String

    Popup window height.

    Defaults to '70%'

    [ options ] : String

    Popup window features.

    Defaults to 'location=no,menubar=no,toolbar=no,dependent=yes,minimizable=no,modal=yes,alwaysRaised=yes,resizable=yes,scrollbars=yes'

  • removeAllListeners()

    See source

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

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

    removeMenuItem( name )

    See source

    Removes a particular menu item added before from the editor context menu.

    Parameters

    name : String

    The name of the desired menu item.

  • removeStyle( style )

    See source

    Removes the style from the editor's current selection. Shorthand for CKEDITOR.style.remove.

    Parameters

    style : style

  • resetDirty()

    See source

    Resets the "dirty state" of the editor so subsequent calls to checkDirty will return false if the user will not have made further changes to the content.

    alert( editor.checkDirty() ); // e.g. true
editor.resetDirty();
alert( editor.checkDirty() ); // false

  • resetUndo()

    See source

    Resets the undo stack.

  • resize( width, height, [ isContentHeight ], [ resizeInner ] )

    See source

    Resizes the editor interface.

    Note: Since 4.14.1 this method accepts numeric or absolute CSS length units.

    editor.resize( 900, 300 );

editor.resize( '5in', 450, true );

    Parameters

    width : Number | String

    The new width. It can be an integer denoting a value in pixels or a CSS size value with unit. When null is passed, the value will not be set.

    height : Number | String

    The new height. It can be an integer denoting a value in pixels or a CSS size value with unit.

    [ isContentHeight ] : Boolean

    Indicates that the provided height is to be applied to the editor content area, and not to the entire editor interface. Defaults to false.

    [ resizeInner ] : Boolean

    Indicates that it is the inner interface element that must be resized, not the outer element. The default theme defines the editor interface inside a pair of <span> elements (<span><span>...</span></span>). By default the first, outer <span> element receives the sizes. If this parameter is set to true, the second, inner <span> is resized instead.

  • restoreRealElement( fakeElement ) → element | null

    See source

    Creates CKEDITOR.dom.element from fake element.

    Parameters

    fakeElement : element

    Fake element to transform.

    Returns

    element | null

    Returns real element or null if transformed element wasn't fake.

  • selectionChange( [ checkNow ] )

    See source

    Check the selection change in editor and potentially fires the selectionChange event.

    Parameters

    [ checkNow ] : Boolean

    Force the check to happen immediately instead of coming with a timeout delay (default).

    Defaults to false

  • since 4.3.0

    setActiveEnterMode( enterMode, shiftEnterMode )

    See source

    Sets the active Enter modes: (enterMode and shiftEnterMode). Fires the activeEnterModeChange event.

    Prior to CKEditor 4.3.0 Enter modes were static and it was enough to check CKEDITOR.config.enterMode and CKEDITOR.config.shiftEnterMode when implementing a feature which should depend on the Enter modes. Since CKEditor 4.3.0 these options are source of initial:

    However, the dynamic Enter modes can be changed during runtime by using this method, to reflect the selection context. For example, if selection is moved to the widget's nested editable which is a blockless one, then the active Enter modes should be changed to CKEDITOR.ENTER_BR (in this case Widget System takes care of that).

    Note: This method should not be used to configure the editor – use CKEDITOR.config.enterMode and CKEDITOR.config.shiftEnterMode instead. This method should only be used to dynamically change Enter modes during runtime based on selection changes. Keep in mind that changed Enter mode may be overwritten by another plugin/feature when it decided that the changed context requires this.

    Note: In case of blockless editor (inline editor based on an element which cannot contain block elements — see blockless) only CKEDITOR.ENTER_BR is a valid Enter mode. Therefore this method will not allow to set other values.

    Note: Changing the active filter may cause the Enter mode to change if default Enter modes are not allowed by the new filter.

    Parameters

    enterMode : Number

    One of CKEDITOR.ENTER_P, CKEDITOR.ENTER_DIV, CKEDITOR.ENTER_BR. Pass falsy value (e.g. null) to reset the Enter mode to the default value (enterMode and/or shiftEnterMode).

    shiftEnterMode : Number

    See the enterMode argument.

  • since 4.3.0

    setActiveFilter( filter )

    See source

    Sets the active filter (activeFilter). Fires the activeFilterChange event.

    // Set active filter which allows only 4 elements.
// Buttons like Bold, Italic will be disabled.
var filter = new CKEDITOR.filter( 'p strong em br' );
editor.setActiveFilter( filter );

    Setting a new filter will also change the active Enter modes to the first values allowed by the new filter (see CKEDITOR.filter.getAllowedEnterMode).

    Parameters

    filter : filter

    Filter instance or a falsy value (e.g. null) to reset to the default one.

  • setData( data, [ options ], [ internal ] )

    See source

    Sets the editor data. The data must be provided in the "raw" format (HTML).

    Note that this method is asynchronous. The callback parameter must be used if interaction with the editor is needed after setting the data.

    CKEDITOR.instances.editor1.setData( '<p>This is the editor data.</p>' );

CKEDITOR.instances.editor1.setData( '<p>Some other editor data.</p>', {
    callback: function() {
        this.checkDirty(); // true
    }
} );

    Note: In CKEditor 4.4.2 the signature of this method has changed. All arguments except data were wrapped into the options object. However, backward compatibility was preserved and it is still possible to use the data, callback, internal arguments.

    Parameters

    data : String

    The HTML code to replace current editor content.

    [ options ] : Object
    [ internal ] : Boolean

    Old equivalent of options.internal parameter. It is only available to provide backwards compatibility for calls with data, callback, internal parameters. It is recommended to use options.internal parameter instead.

    Defaults to false

  • since 4.0.0

    setKeystroke( keystroke, [ behavior ] )

    See source

    Assigns keystrokes associated with editor commands.

    editor.setKeystroke( CKEDITOR.CTRL + 115, 'save' ); // Assigned Ctrl+S to the "save" command.
editor.setKeystroke( CKEDITOR.CTRL + 115, false );  // Disabled Ctrl+S keystroke assignment.
editor.setKeystroke( [
    [ CKEDITOR.ALT + 122, false ],
    [ CKEDITOR.CTRL + 121, 'link' ],
    [ CKEDITOR.SHIFT + 120, 'bold' ]
] );

    This method may be used in the following cases:

    • By plugins (like link or basicstyles) to set their keystrokes when plugins are being loaded.
    • During the runtime to modify existing keystrokes.

    The editor handles keystroke configuration in the following order:

    1. Plugins use this method to define default keystrokes.
    2. Editor extends default keystrokes with CKEDITOR.config.keystrokes.
    3. Editor blocks keystrokes defined in CKEDITOR.config.blockedKeystrokes.

    You can then set new keystrokes using this method during the runtime.

    Parameters

    keystroke : Number | Array

    A keystroke or an array of keystroke definitions.

    [ behavior ] : String | Boolean

    A command to be executed on the keystroke.

  • setMode( [ newMode ], [ callback ] )

    See source

    Changes the editing mode of this editor instance.

    Note: The mode switch could be asynchronous depending on the mode provider. Use the callback to hook subsequent code.

    // Switch to "source" view.
CKEDITOR.instances.editor1.setMode( 'source' );
// Switch to "wysiwyg" view and be notified on completion.
CKEDITOR.instances.editor1.setMode( 'wysiwyg', function() { alert( 'wysiwyg mode loaded!' ); } );

    Parameters

    [ newMode ] : String

    If not specified, the CKEDITOR.config.startupMode will be used.

    [ callback ] : Function

    Optional callback function which is invoked once the mode switch has succeeded.

  • since 3.6.0

    setReadOnly( [ isReadOnly ] )

    See source

    Puts or restores the editor into the read-only state. When in read-only, the user is not able to change the editor content, but can still use some editor features. This function sets the readOnly property of the editor, firing the readOnly event.

    Note: The current editing area will be reloaded.

    Parameters

    [ isReadOnly ] : Boolean

    Indicates that the editor must go read-only (true, default) or be restored and made editable (false).

  • setUiColor( color )

    See source

    Sets the color of the editor user interface. This method accepts a color value in hexadecimal notation, with a # character (e.g. #ffffff).

        CKEDITOR.instances.editor1.setUiColor( '#ff00ff' );

    Parameters

    color : String

    The desired editor UI color in hexadecimal notation.

  • since 4.5.0

    showNotification( message, [ type ], [ progressOrDuration ] ) → notification

    See source

    Shows a notification to the user.

    If the Notification plugin is not enabled, this function shows a normal alert with the given message. The type and progressOrDuration parameters are supported only by the Notification plugin.

    If the Notification plugin is enabled, this method creates and shows a new notification. By default the notification is shown over the editor content, in the viewport if it is possible.

    See CKEDITOR.plugins.notification.

    Parameters

    message : String

    The message displayed in the notification.

    [ type ] : String

    The type of the notification. Can be 'info', 'warning', 'success' or 'progress'.

    Defaults to 'info'

    [ progressOrDuration ] : Number

    If the type is progress, the third parameter may be a progress from 0 to 1 (defaults to 0). Otherwise the third parameter may be a notification duration denoting after how many milliseconds the notification should be closed automatically. 0 means that the notification will not close automatically and the user needs to close it manually. See CKEDITOR.plugins.notification.duration. Note that warning notifications will not be closed automatically.

    Returns

    notification

    Created and shown notification.

  • unlockSelection( [ restore ] )

    See source

    Unlocks the selection made in the editor and locked with the lockSelection method. An unlocked selection is no longer cached and can be changed.

    Parameters

    [ restore ] : Boolean

    If set to true, the selection is restored back to the selection saved earlier by using the CKEDITOR.dom.selection.lock method.

  • updateElement()

    See source

    Updates the <textarea> element that was replaced by the editor with the current data available in the editor.

    Note: This method will only affect those editor instances created with the CKEDITOR.ELEMENT_MODE_REPLACE element mode or inline instances bound to <textarea> elements.

    CKEDITOR.instances.editor1.updateElement();
alert( document.getElementById( 'editor1' ).value ); // The current editor data.

    CKEDITOR.editor.element

  • private

    _attachToForm()

    See source

    Attaches the editor to a form to call updateElement before form submission. This method is called by both creators (replace and inline), so there is no reason to call it manually.

Static methods

  • 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.12.0 private static

    _getEditorElement( elementOrId ) → element | null

    See source

    Gets the element from the DOM and checks if the editor can be instantiated on it. This function is available for internal use only.

    Parameters

    elementOrId : String | element

    Returns

    element | null

  • since 4.17.0 private static

    initializeDelayedEditorCreation( element, config, editorCreationMethod ) → Function | null

    See source

    Initializes delayed editor creation based on provided configuration.

    If the CKEDITOR.config.delayIfDetached_callback function is declared, it will be invoked with a single argument:

    • A callback, that should be called to create editor.

    Otherwise, it periodically (with setInterval() calls) checks if element is attached to DOM and creates editor automatically. The interval can be canceled by executing a callback function (a handle) clearing the interval.

    CKEDITOR.inline( detachedEditorElement, {
    delayIfDetached: true,
    delayIfDetached_callback: registerCallback
} );

    Parameters

    element : element

    The DOM element on which editor should be initialized.

    config : Object

    The specific configuration to apply to the editor instance. Configuration set here will override the global CKEditor settings.

    editorCreationMethod : String

    Creator function that should be used to initialize editor (inline/replace).

    Returns

    Function | null

    A handle allowing to cancel delayed editor initialization creation or null if CKEDITOR.config.delayIfDetached_callback option is set.

  • since 4.17.0 private static

    mergeDelayedCreationConfigs( userConfig )

    See source

    Merges user provided configuration options for delayed creation with default config.

    User provided options are the preferred ones.

    Parameters

    userConfig : Object

    Config provided by the user to create editor.

  • since 4.17.0 private static

    shouldDelayEditorCreation( element, config ) → Boolean

    See source

    Whether editor creation should be delayed.

    Parameters

    element : element

    The DOM element on which editor should be initialized.

    config : Object

    Editor configuration.

    Returns

    Boolean

    True if creation should be delayed.

Events

  • since 4.3.0

    activeEnterModeChange( evt )

    See source

    Event fired by the setActiveEnterMode method when any of the active Enter modes is changed. See also the activeEnterMode and activeShiftEnterMode properties.

    Parameters

    evt : eventInfo

  • since 4.3.0

    activeFilterChange( evt )

    See source

    Event fired by the setActiveFilter method when the activeFilter is changed.

    Parameters

    evt : eventInfo

  • afterCommandExec( evt )

    See source

    Event fired after the command execution when execCommand is called.

    Parameters

    evt : eventInfo

  • since 4.5.0

    afterInsertHtml( evt )

    See source

    Event fired after data insertion using the insertHtml, CKEDITOR.editable.insertHtml, or CKEDITOR.editable.insertHtmlIntoRange methods.

    Parameters

    evt : eventInfo

  • afterPaste( evt )

    See source

    Fired after the paste event if content was modified. Note that if the paste event does not insert any data, the afterPaste event will not be fired.

    Parameters

    evt : eventInfo

  • since 4.6.0

    afterPasteFromWord( evt )

    See source

    Fired after the Paste form Word filters have been applied.

    Parameters

    evt : eventInfo

  • afterSetData( evt )

    See source

    Event fired at the end of the setData call execution. Usually it is better to use the dataReady event.

    Parameters

    evt : eventInfo

  • since 3.5.3

    afterUndoImage( evt )

    See source

    Fired after an undo image is created. An undo image represents the editor state at some point. It is saved into the undo store, so the editor is able to recover the editor state on undo and redo operations.

    Parameters

    evt : eventInfo

  • since 4.4.3

    ariaEditorHelpLabel( evt )

    See source

    Event fired by the editor in order to get accessibility help label. The event is responded to by a component which provides accessibility help (i.e. the a11yhelp plugin) hence the editor is notified whether accessibility help is available.

    Providing info:

    editor.on( 'ariaEditorHelpLabel', function( evt ) {
        evt.data.label = editor.lang.common.editorHelp;
} );

    Getting label:

    var helpLabel = editor.fire( 'ariaEditorHelpLabel', {} ).label;

    Parameters

    evt : eventInfo

  • ariaWidget( evt )

    See source

    Fired when some elements are added to the document.

    Parameters

    evt : eventInfo

  • autogrow( evt )

    See source

    Fired when the Auto Grow plugin is about to change the size of the editor.

    Parameters

    evt : eventInfo

  • beforeCommandExec( evt )

    See source

    Event fired before the command execution when execCommand is called.

    Parameters

    evt : eventInfo

  • beforeDestroy( evt )

    See source

    Event fired when the destroy method is called, but before destroying the editor.

    Parameters

    evt : eventInfo

  • beforeGetData( evt )

    See source

    Internal event to get the current data.

    Parameters

    evt : eventInfo

  • beforeModeUnload( evt )

    See source

    Fired before changing the editing mode. See also beforeSetMode and mode.

    Parameters

    evt : eventInfo

  • deprecated

    beforePaste( evt )

    See source

    Fired before the paste event. Allows to preset data type.

    Note: This event is deprecated. Add a 0 priority listener for the paste event instead.

    Parameters

    evt : eventInfo

  • since 3.5.3

    beforeSetMode( evt )

    See source

    Fired before the editor mode is set. See also mode and beforeModeUnload.

    Parameters

    evt : eventInfo

  • since 3.5.3

    beforeUndoImage( evt )

    See source

    Fired before an undo image is to be created. An undo image represents the editor state at some point. It is saved into the undo store, so the editor is able to recover the editor state on undo and redo operations.

    Parameters

    evt : eventInfo

  • blur( evt )

    See source

    Fired when the editor instance loses the input focus.

    Note: This event will NOT be triggered when focus is moved internally, e.g. from an editable to another part of the editor UI like a dialog window. If you are interested only in the focus state of the editable, listen to the focus and blur events of the CKEDITOR.editable instead.

    editor.on( 'blur', function( e ) {
    alert( 'The editor named ' + e.editor.name + ' lost the focus' );
} );

    Parameters

    evt : eventInfo

  • since 4.2.0

    change( evt )

    See source

    Fired when the content of the editor is changed.

    Due to performance reasons, it is not verified if the content really changed. The editor instead watches several editing actions that usually result in changes. This event may thus in some cases be fired when no changes happen or may even get fired twice.

    If it is important not to get the change event fired too often, you should compare the previous and the current editor content inside the event listener. It is not recommended to do that on every change event.

    Please note that the change event is only fired in the wysiwyg mode. In order to implement similar functionality in the source mode, you can listen for example to the event-key event or the native input event (not supported by Internet Explorer 8).

    editor.on( 'mode', function() {
    if ( this.mode == 'source' ) {
        var editable = editor.editable();
        editable.attachListener( editable, 'input', function() {
            // Handle changes made in the source mode.
        } );
    }
} );

    Parameters

    evt : eventInfo

  • configLoaded( evt )

    See source

    Event fired once the editor configuration is ready (loaded and processed).

    Parameters

    evt : eventInfo

  • contentDirChanged( evt )

    See source

    Fired when the language direction in the specific cursor position is changed

    Parameters

    evt : eventInfo

  • contentDom( evt )

    See source

    Event fired when the editor content (its DOM structure) is ready. It is similar to the native DOMContentLoaded event, but it applies to the editor content. It is also the first event fired after the CKEDITOR.editable is initialized.

    This event is particularly important for classic (iframe-based) editor, because on editor initialization and every time the data are set (by setData) content DOM structure is rebuilt. Thus, e.g. you need to attach DOM event listeners on editable one more time.

    For inline editor this event is fired only once — when the editor is initialized for the first time. This is because setting editor content does not cause editable destruction and creation.

    The contentDom event goes along with contentDomUnload which is fired before the content DOM structure is destroyed. This is the right moment to detach content DOM event listener. Otherwise browsers like IE or Opera may throw exceptions when accessing elements from the detached document.

    Note: CKEDITOR.editable.attachListener is a convenient way to attach listeners that will be detached on contentDomUnload.

    editor.on( 'contentDom', function() {
    var editable = editor.editable();

    editable.attachListener( editable, 'click', function() {
        console.log( 'The editable was clicked.' );
    });
});

    Parameters

    evt : eventInfo

  • since 4.3.0

    contentDomInvalidated( evt )

    See source

    Event fired when the content DOM changes and some of the references as well as the native DOM event listeners could be lost. This event is useful when it is important to keep track of references to elements in the editable content from code.

    Parameters

    evt : eventInfo

  • contentDomUnload( evt )

    See source

    Event fired before the content DOM structure is destroyed. See contentDom documentation for more details.

    Parameters

    evt : eventInfo

  • contentPreview( evt )

    See source

    Event fired when executing the preview command that allows for additional data manipulation. With this event, the raw HTML content of the preview window to be displayed can be altered or modified.

    Note This event should also be used to sanitize HTML to mitigate possible XSS attacks. Refer to the Validate preview content section of the Best Practices article to learn more.

    Parameters

    evt : eventInfo

  • customConfigLoaded( evt )

    See source

    Event fired when a custom configuration file is loaded, before the final configuration initialization.

    Custom configuration files can be loaded thorugh the CKEDITOR.config.customConfig setting. Several files can be loaded by changing this setting.

    Parameters

    evt : eventInfo

  • since 4.1.0

    dataFiltered( evt )

    See source

    This event is fired when CKEDITOR.filter has stripped some content from the data that was loaded (e.g. by setData method or in the source mode) or inserted (e.g. when pasting or using the insertHtml method).

    This event is useful when testing whether the CKEDITOR.config.allowedContent setting is sufficient and correct for a system that is migrating to CKEditor 4.1.0 (where the Advanced Content Filter was introduced).

    Parameters

    evt : eventInfo

  • dataReady( evt )

    See source

    Event fired as an indicator of the editor data loading. It may be the result of calling setData explicitly or an internal editor function, like the editor editing mode switching (move to Source and back).

    Parameters

    evt : eventInfo

  • destroy( evt )

    See source

    Event fired when this editor instance is destroyed. The editor at this point is not usable and this event should be used to perform the clean-up in any plugin.

    Parameters

    evt : eventInfo

  • dialogHide( evt )

    See source

    Event fired when a dialog is hidden.

    Parameters

    evt : eventInfo

  • dialogShow( evt )

    See source

    Event fired when a dialog is shown.

    Parameters

    evt : eventInfo

  • dirChanged( evt )

    See source

    Fired when the language direction of an element is changed.

    Parameters

    evt : eventInfo

  • doubleclick( evt )

    See source

    Event fired when the user double-clicks in the editable area. The event allows to open a dialog window for a clicked element in a convenient way:

    editor.on( 'doubleclick', function( evt ) {
    var element = evt.data.element;

    if ( element.is( 'table' ) )
        evt.data.dialog = 'tableProperties';
} );

    Note: To handle double-click on a widget use CKEDITOR.plugins.widget.doubleclick.

    Parameters

    evt : eventInfo

  • since 4.5.0

    dragend( evt )

    See source

    Facade for the native dragend event. Fired when the native dragend event occurs.

    Read more about integration with drag and drop in the Clipboard Deep Dive guide.

    See also:

    Parameters

    evt : eventInfo

  • since 4.5.0

    dragstart( evt )

    See source

    Facade for the native dragstart event. Fired when the native dragstart event occurs.

    This event can be canceled in order to block the drag start operation. It can also be fired to mimic the start of the drag and drop operation. For instance, the widget plugin uses this option to integrate its custom block widget drag and drop with the entire system.

    Read more about integration with drag and drop in the Clipboard Deep Dive guide.

    See also:

    Parameters

    evt : eventInfo

  • since 4.5.0

    drop( evt )

    See source

    Facade for the native drop event. Fired when the native drop event occurs.

    Note: To manipulate dropped data, use the paste event. Use the drop event only to control drag and drop operations (e.g. to prevent the ability to drop some content).

    Read more about integration with drag and drop in the Clipboard Deep Dive guide.

    See also:

    Parameters

    evt : eventInfo

  • elementsPathUpdate( evt )

    See source

    Fired when the contents of the elementsPath are changed.

    Parameters

    evt : eventInfo

  • since 4.15.0

    exportPdf( evt )

    Event fired when executing the exportPdf command that allows for additional data manipulation. With this event, the raw HTML content of the editor which will be sent to the HTML to PDF converter service can be altered or modified. It also allows to modify CSS rules and conversion options.

    It is possible by adding listeners with the different priorities:

    • 1-14: The data is available in the original string format.
    • 15: The data is processed by the plugin.
    • 16-19: The data that will be sent to the endpoint can be modified.
    • 20: The data is sent to the endpoint.

    Read more in the documentation.

    Parameters

    evt : eventInfo

  • since 4.5.0

    fileUploadRequest( evt )

    See source

    Event fired when the file loader should send XHR. If the event is not stopped or canceled, the default request will be sent. Refer to the Uploading Dropped or Pasted Files article for more information.

    Parameters

    evt : eventInfo

  • since 4.5.0

    fileUploadResponse( evt )

    See source

    Event fired when the file upload response is received and needs to be parsed. If the event is not stopped or canceled, the default response handler will be used. Refer to the Uploading Dropped or Pasted Files article for more information.

    Parameters

    evt : eventInfo

  • since 4.5.0

    floatingSpaceLayout( evt )

    See source

    Fired when the viewport or editor parameters change and the floating space needs to check and eventually update its position and dimensions.

    Parameters

    evt : eventInfo

  • focus( evt )

    See source

    Fired when the editor instance receives the input focus.

    editor.on( 'focus', function( e ) {
    alert( 'The editor named ' + e.editor.name + ' is now focused' );
} );

    Parameters

    evt : eventInfo

  • getData( evt )

    See source

    Event fired before the getData call returns, allowing for additional manipulation.

    Parameters

    evt : eventInfo

  • getSnapshot( evt )

    See source

    Internal event to perform the getSnapshot call.

    Parameters

    evt : eventInfo

  • insertElement( evt )

    See source

    Event fired by the insertElement method. See the method documentation for more information about how this event can be used.

    Parameters

    evt : eventInfo

  • insertHtml( evt )

    See source

    Event fired by the insertHtml method. See the method documentation for more information about how this event can be used.

    Parameters

    evt : eventInfo

  • insertText( evt )

    See source

    Event fired by the insertText method. See the method documentation for more information about how this event can be used.

    Parameters

    evt : eventInfo

  • instanceReady( evt )

    See source

    Event fired when the CKEDITOR instance is completely created, fully initialized and ready for interaction.

    Parameters

    evt : eventInfo

  • key( evt )

    See source

    Fired when any keyboard key (or a combination thereof) is pressed in the editing area.

    editor.on( 'key', function( evt ) {
    if ( evt.data.keyCode == CKEDITOR.CTRL + 90 ) {
        // Do something...

        // Cancel the event, so other listeners will not be executed and
        // the keydown's default behavior will be prevented.
        evt.cancel();
    }
} );

    Usually you will want to use the setKeystroke method or the CKEDITOR.config.keystrokes option to attach a keystroke to some command. Key event listeners are usuful when some action should be executed conditionally, based for example on precise selection location.

    Parameters

    evt : eventInfo

  • since 3.6.1

    langLoaded( evt )

    See source

    Event fired when the language is loaded into the editor instance.

    Parameters

    evt : eventInfo

  • loadSnapshot( evt )

    See source

    Internal event to perform the loadSnapshot call.

    Parameters

    evt : eventInfo

  • loaded( evt )

    See source

    Event fired when editor components (configuration, languages and plugins) are fully loaded and initialized. However, the editor will be fully ready to for interaction on instanceReady.

    Parameters

    evt : eventInfo

  • since 4.0.0

    lockSnapshot( evt )

    See source

    Locks the undo manager to prevent any save/update operations.

    It is convenient to lock the undo manager before performing DOM operations that should not be recorded (e.g. auto paragraphing).

    See CKEDITOR.plugins.undo.UndoManager.lock for more details.

    Note: In order to unlock the undo manager, unlockSnapshot has to be fired the same number of times that lockSnapshot has been fired.

    Parameters

    evt : eventInfo

  • maximize( evt )

    See source

    Event fired when the maximize command is called. It also indicates whether an editor is maximized or not.

    Parameters

    evt : eventInfo

  • menuShow( evt )

    See source

    Fired when a menu is shown.

    Parameters

    evt : eventInfo

  • mode( evt )

    See source

    Fired after setting the editing mode. See also beforeSetMode and beforeModeUnload

    Parameters

    evt : eventInfo

  • since 4.5.0

    notificationHide( evt )

    See source

    Event fired when the CKEDITOR.plugins.notification.hide method is called, before the notification is hidden. If this event is canceled, the notification will not be hidden.

    Using this event allows you to fully customize how a notification will be hidden. It may be used to integrate the CKEditor notification system with your web page notifications.

    Parameters

    evt : eventInfo

  • since 4.5.0

    notificationShow( evt )

    See source

    Event fired when the CKEDITOR.plugins.notification.show method is called, before the notification is shown. If this event is canceled, the notification will not be shown.

    Using this event allows you to fully customize how a notification will be shown. It may be used to integrate the CKEditor notification system with your web page notifications.

    Parameters

    evt : eventInfo

  • since 4.5.0

    notificationUpdate( evt )

    See source

    Event fired when the CKEDITOR.plugins.notification.update method is called, before the notification is updated. If this event is canceled, the notification will not be shown even if the update was important, but the object will be updated anyway. Note that canceling this event does not prevent updating element attributes, but if notificationShow was canceled as well, this element is detached from the DOM.

    Using this event allows you to fully customize how a notification will be updated. It may be used to integrate the CKEditor notification system with your web page notifications.

    Parameters

    evt : eventInfo

  • since 3.1.0

    paste( evt )

    See source

    Fired after the user initiated a paste action, but before the data is inserted into the editor. The listeners to this event are able to process the content before its insertion into the document.

    Read more about the integration with clipboard in the Clipboard Deep Dive guide.

    See also:

    Parameters

    evt : eventInfo

  • private

    pasteDialog( evt )

    See source

    Internal event to open the Paste dialog window.

    This event was not available in 4.7.0-4.8.0 versions.

    Parameters

    evt : eventInfo

  • private

    pasteDialogCommit( evt )

    See source

    Internal event to pass the paste dialog data to the listeners.

    This event was not available in versions 4.7.0-4.8.0.

    Parameters

    evt : eventInfo

  • since 4.6.0

    pasteFromWord( evt )

    See source

    Fired when the pasted content was recognized as Microsoft Word content.

    This event is cancellable. If canceled, it will prevent Paste from Word processing.

    Parameters

    evt : eventInfo

  • pluginsLoaded( evt )

    See source

    Event fired when all plugins are loaded and initialized into the editor instance.

    Parameters

    evt : eventInfo

  • since 3.6.0

    readOnly( evt )

    See source

    Event fired after the readOnly property changes.

    Parameters

    evt : eventInfo

  • removeFormatCleanup( evt )

    See source

    Fired after an element was cleaned by the removeFormat plugin.

    Parameters

    evt : eventInfo

  • required( evt )

    See source

    Fired when the editor (replacing a <textarea> which has a required attribute) is empty during form submission.

    This event replaces native required fields validation that the browsers cannot perform when CKEditor replaces <textarea> elements.

    You can cancel this event to prevent the page from submitting data.

    editor.on( 'required', function( evt ) {
    alert( 'Article content is required.' );
    evt.cancel();
} );

    Parameters

    evt : eventInfo

  • resize( evt )

    See source

    Fired after the editor instance is resized through the CKEDITOR.resize method.

    Parameters

    evt : eventInfo

  • since 4.2.0

    save( evt )

    See source

    Fired when the user clicks the Save button on the editor toolbar. This event allows to overwrite the default Save button behavior.

    Parameters

    evt : eventInfo

  • saveSnapshot( evt )

    See source

    Fired when the editor is about to save an undo snapshot. This event can be fired by plugins and customizations to make the editor save undo snapshots.

    Parameters

    evt : eventInfo

  • selectionChange( evt )

    See source

    Fired when selection inside editor has been changed. Note that this event is fired only when selection's start element (container of a selecion start) changes, not on every possible selection change. Thanks to that selectionChange is fired less frequently, but on every context (the elements path holding selection's start) change.

    Parameters

    evt : eventInfo

  • setData( evt )

    See source

    Event fired before the setData call is executed, allowing for additional manipulation.

    Parameters

    evt : eventInfo

  • since 4.15.1

    stylesRemove( evt )

    See source

    Removes styles from the current editor selection.

    Note that you can pass the type option to limit removing styles to the given type.

    editor.fire( 'stylesRemove', { type: CKEDITOR.STYLE_BLOCK } );

    Parameters

    evt : eventInfo

  • since 4.1.0

    stylesSet( evt )

    See source

    Event fired when the styles set is loaded. During the editor initialization phase the getStylesSet method returns only styles that are already loaded, which may not include e.g. styles parsed by the stylesheetparser plugin. Thus, to be notified when all styles are ready, you can listen on this event.

    Parameters

    evt : eventInfo

  • template( evt )

    See source

    Event fired when a UI template is added to the editor instance. It makes it possible to bring customizations to the template source.

    Parameters

    evt : eventInfo

  • since 4.1.0

    toDataFormat( evt )

    See source

    This event is fired when CKEDITOR.htmlDataProcessor is converting internal HTML to output data HTML.

    By adding listeners with different priorities it is possible to process input HTML on different stages:

    For example to be able to process parsed and already processed data add listener this way:

    editor.on( 'toDataFormat', function( evt) {
    evt.data.dataValue; // -> CKEDITOR.htmlParser.fragment instance
}, null, null, 12 );

    Parameters

    evt : eventInfo

  • since 4.1.0

    toHtml( evt )

    See source

    This event is fired by the CKEDITOR.htmlDataProcessor when input HTML is to be purified by the CKEDITOR.htmlDataProcessor.toHtml method.

    By adding listeners with different priorities it is possible to process input HTML on different stages:

    For example to be able to process parsed, but not yet filtered data add listener this way:

    editor.on( 'toHtml', function( evt) {
    evt.data.dataValue; // -> CKEDITOR.htmlParser.fragment instance
}, null, null, 7 );

    Parameters

    evt : eventInfo

  • uiSpace( evt )

    See source

    Fired when the UI space is created. This event allows to modify the top bar or the bottom bar with additional HTML.

    For example, it is used in the Editor Resize plugin to add the HTML element used to resize the editor.

    Parameters

    evt : eventInfo

  • since 4.0.0

    unlockSnapshot( evt )

    See source

    Unlocks the undo manager and updates the latest snapshot.

    Parameters

    evt : eventInfo

  • updateSnapshot( evt )

    See source

    Amends the top of the undo stack (last undo image) with the current DOM changes.

    function() {
    editor.fire( 'saveSnapshot' );
    editor.document.body.append(...);
    // Makes new changes following the last undo snapshot a part of it.
    editor.fire( 'updateSnapshot' );
    ..
}

    Parameters

    evt : eventInfo

  • widgetDefinition( evt )

    See source

    An event fired when a widget definition is registered by the CKEDITOR.plugins.widget.repository.add method. It is possible to modify the definition being registered.

    Parameters

    evt : eventInfo