Report an issue
Class

CKEDITOR.editor

class

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

Filtering

Properties

  • activeEnterMode : Number

    since 4.3 readonly

    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.

  • activeFilter : filter

    since 4.3 readonly

    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.

  • activeShiftEnterMode : Number

    since 4.3 readonly

    See the activeEnterMode property.

  • balloonToolbars : contextManager

    since 4.8 readonly

    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'
    } );
    
  • blockless : Boolean

    readonly

    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.

  • config : config

    readonly

    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'
    
  • container : element

    readonly

    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'
    
  • contextMenu : contextMenu

    readonly

  • copyFormatting : state

    since 4.6.0

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

  • dataProcessor : dataProcessor

    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.

  • document : document

    readonly

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

    readonly

    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.

  • elementMode : Number

    readonly

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

  • enterMode : Number

    since 4.3 readonly

    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.

  • filter : filter

    since 4.1 readonly

    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.

  • focusManager : focusManager

    readonly

    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.

  • id : String

    readonly

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

  • keystrokeHandler : keystrokeHandler

    readonly

    Controls keystroke typing in this editor instance.

  • lang : Object

    readonly

    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)
    
  • langCode : String

    readonly

    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'
    
  • mode : String

    readonly

    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'
    
  • name : String

    readonly

    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.

  • pasteFilter : filter

    since 4.5 readonly

    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.

  • plugins : plugins

    readonly

    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 ) {
        ...
    }
    
  • readOnly : Boolean

    since 3.6 readonly

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

  • shiftEnterMode : Number

    since 4.3 readonly

    See the enterMode property.

  • status : String

    since 4.1 readonly

    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.
    • ready: The editor is fully initialized and ready — see the instanceReady event.
    • destroyed: The editor was destroyed — see the destroy method.

    Defaults to 'unloaded'

  • tabIndex : Number

    readonly

    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

  • templates : Object

    readonly

    Contains all UI templates created for this editor instance.

    Defaults to {}

  • title : String | Boolean

    since 4.2 readonly

    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.

  • toolbar : Object

    readonly

    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.

  • ui : ui

    readonly

    The namespace containing UI features related to this editor instance.

  • uploadRepository : uploadRepository

    since 4.5 readonly

    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' );
    
  • widgets : repository

    since 4.3 readonly

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

    readonly

    The window instance related to the document property.

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

    See the document property documentation.

Static properties

  • useCapture : Boolean

    mixed static

Methods

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

    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 )

    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.

  • addContentsCss( cssPath )

    since 4.4

    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.

  • addFeature( feature ) → Boolean

    since 4.1

    Shorthand for CKEDITOR.filter.addFeature.

    Parameters

    feature : feature

    See CKEDITOR.filter.addFeature.

    Returns

    Boolean

    See CKEDITOR.filter.addFeature.

  • addMenuGroup( name, [ order ] )

    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 )

    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 )

    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 )

    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.

  • addRemoveFormatFilter( func )

    since 3.3

    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 a {CKEDITOR.dom.element} element to test.

  • applyStyle( style )

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

    Parameters

    style : style
  • attachStyleStateChange( style, callback )

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

    Register event handler under the capturing stage on supported target.

  • checkDirty() → Boolean

    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

    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

    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

    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 )

    Predefine some intrinsic properties on a specific event name.

    Parameters

    name : String

    The event name

    meta : Object
    Properties
    [ errorProof ]

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

    Defaults to false

  • destroy( [ noUpdate ] )

    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

    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

    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

    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

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

    since 4.5

    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

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

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

  • forceNextSelectionCheck()

  • getClipboardData( callbackOrOptions, callback )

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

    Open up color dialog and to receive the selected color.

    Parameters

    callback : Function

    The callback when color dialog is closed

    Properties
    color : String

    The color value received if selected on the dialog.

    [ scope ] : Object

    The scope in which the callback will be bound.

  • getCommand( commandName ) → command

    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.

  • getCommandKeystroke( command ) → Number | null

    since 4.6.0

    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.

    Returns

    Number | null

    The keystroke assigned to the provided command or null if there is no keystroke.

  • getData( internal ) → String

    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

    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

    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.

  • getSelectedHtml( [ toString ] ) → documentFragment | String

    since 4.5

    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
  • getSelection( forceRealSelection ) → selection

    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

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

  • getSnapshot() → String

    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 )

    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

    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

    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 )

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

    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.

  • insertText( text )

    since 3.5

    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.

  • loadSnapshot( snapshot )

    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

    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

    Registers a listener to a specific event in the current object.

    someObject.on( 'someEvent', function() {
        alert( this == someObject );        // true
    } );
    
    someObject.on( 'someEvent', function() {
        alert( this == anotherObject );     // true
    }, anotherObject );
    
    someObject.on( 'someEvent', function( event ) {
        alert( event.listenerData );        // 'Example'
    }, null, 'Example' );
    
    someObject.on( 'someEvent', function() { ... } );                       // 2nd called
    someObject.on( 'someEvent', function() { ... }, null, null, 100 );      // 3rd called
    someObject.on( 'someEvent', function() { ... }, null, null, 1 );        // 1st called
    

    Parameters

    eventName : String

    The event name to which listen.

    listenerFunction : Function

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

    [ scopeObj ] : Object

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

    [ listenerData ] : Object

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

    [ priority ] : Number

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

    Defaults to 10

    Returns

    Object

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

  • once()

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

  • openDialog( dialogName, callback ) → dialog

    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 dialog instance created.

    Returns

    dialog

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

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

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

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

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

  • removeMenuItem( name )

    since 3.6.1

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

    Parameters

    name : String

    The name of the desired menu item.

  • removeStyle( style )

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

    Parameters

    style : style
  • resetDirty()

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

    Resets the undo stack.

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

    Resizes the editor interface.

    editor.resize( 900, 300 );
    
    editor.resize( '100%', 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.

    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

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

    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

  • setActiveEnterMode( enterMode, shiftEnterMode )

    since 4.3

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

    Prior to CKEditor 4.3 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 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.

  • setActiveFilter( filter )

    since 4.3

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

    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
    Properties
    [ internal ] : Boolean

    Whether to suppress any event firing when copying data internally inside the editor.

    Defaults to false

    [ callback ] : Function

    Function to be called after setData is completed (on dataReady).

    [ noSnapshot ] : Boolean

    If set to true, it will prevent recording an undo snapshot. Introduced in CKEditor 4.4.2.

    Defaults to false

  • setKeystroke( keystroke, [ behavior ] )

    since 4.0

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

    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.

  • setReadOnly( [ isReadOnly ] )

    since 3.6

    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 )

    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.

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

    since 4.5

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

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

    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

  • _attachToForm()

    private

    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.

Events

  • activeEnterModeChange( evt )

    since 4.3

    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
  • activeFilterChange( evt )

    since 4.3

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

    Parameters

    evt : eventInfo
  • afterCommandExec( evt )

    Event fired after the command execution when execCommand is called.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    name : String

    The command name.

    commandData : Object

    The data sent to the command.

    command : command

    The command itself.

    returnValue : Object

    The value returned by the command execution.

  • afterInsertHtml( evt )

    since 4.5

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

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    [ intoRange ] : range

    If set, the HTML was not inserted into the current selection, but into the specified range. This property is set if the CKEDITOR.editable.insertHtmlIntoRange method was used, but not if for the CKEDITOR.editable.insertHtml method.

  • afterPaste( evt )

    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
  • afterPasteFromWord( evt )

    since 4.6.0

    Fired after the Paste form Word filters have been applied.

    Parameters

    evt : eventInfo
    Properties
    data : Object
    Properties
    dataValue : String

    Pasted content after processing. Changes to this property will affect the pasted content.

  • afterSetData( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    dataValue : String

    The data that has been set.

  • afterUndoImage( evt )

    since 3.5.3

    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
    Properties
    editor : editor

    This editor instance. CKEDITOR.editor.beforeUndoImage

  • ariaEditorHelpLabel( evt )

    since 4.4.3

    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
    Properties
    label : String

    The label to be used.

  • ariaWidget( evt )

    Fired when some elements are added to the document.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : element

    The element being added.

  • autogrow( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    currentHeight : Number

    The current editor height (before resizing).

    newHeight : Number

    The new editor height (after resizing). It can be changed to achieve a different height value to be used instead.

  • beforeCommandExec( evt )

    Event fired before the command execution when execCommand is called.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    name : String

    The command name.

    commandData : Object

    The data to be sent to the command. This can be manipulated by the event listener.

    command : command

    The command itself.

  • beforeDestroy( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • beforeGetData( evt )

    Internal event to get the current data.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • beforeModeUnload( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • beforePaste( evt )

    deprecated

    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
  • beforeSetMode( evt )

    since 3.5.3

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : String

    The name of the mode which is about to be set.

  • beforeUndoImage( evt )

    since 3.5.3

    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
    Properties
    editor : editor

    This editor instance. CKEDITOR.editor.afterUndoImage

  • blur( evt )

    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
    Properties
    editor : editor

    The editor instance.

  • change( evt )

    since 4.2

    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 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
    Properties
    editor : editor

    This editor instance.

  • configLoaded( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • contentDirChanged( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : String

    The direction in the current position.

  • contentDom( evt )

    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
    Properties
    editor : editor

    This editor instance.

  • contentDomInvalidated( evt )

    since 4.3

    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
    Properties
    editor : editor

    This editor instance.

  • contentDomUnload( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • customConfigLoaded( evt )

    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
    Properties
    editor : editor

    This editor instance.

  • dataFiltered( evt )

    since 4.1

    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 (where the Advanced Content Filter was introduced).

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • dataReady( evt )

    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
    Properties
    editor : editor

    This editor instance.

  • destroy( evt )

    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
    Properties
    editor : editor

    This editor instance.

  • dialogHide( evt )

    Event fired when a dialog is hidden.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : dialog

    The hidden dialog instance.

  • dialogShow( evt )

    Event fired when a dialog is shown.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : dialog

    The opened dialog instance.

  • dirChanged( evt )

    Fired when the language direction of an element is changed.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    node : node

    The element that is being changed.

    dir : String

    The new direction.

  • doubleclick( evt )

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

    The double-clicked element.

    dialog : String

    The dialog window to be opened. If set by the listener, the specified dialog window will be opened.

  • dragend( evt )

    since 4.5

    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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    $ : Object

    Native dragend event.

    target : node

    Drag target.

    dataTransfer : dataTransfer

    DataTransfer facade.

  • dragstart( evt )

    since 4.5

    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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    $ : Object

    Native dragstart event.

    target : node

    Drag target.

    dataTransfer : dataTransfer

    DataTransfer facade.

  • drop( evt )

    since 4.5

    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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    $ : Object

    Native drop event.

    target : node

    Drop target.

    dataTransfer : dataTransfer

    DataTransfer facade.

    dragRange : range

    Drag range, lets you manipulate the drag range. Note that dragged HTML is saved as text/html data on dragstart so if you change the drag range on drop, dropped HTML will not change. You need to change it manually using dataTransfer.setData.

    dropRange : range

    Drop range, lets you manipulate the drop range.

  • elementsPathUpdate( evt )

    Fired when the contents of the elementsPath are changed.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    space : element

    The elementsPath container.

  • fileUploadRequest( evt )

    since 4.5

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

    A file loader instance.

    requestData : Object

    An object containing all data to be sent to the server.

  • fileUploadResponse( evt )

    since 4.5

    Event fired when the {CKEDITOR.fileTools.fileLoader 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
    Properties
    data : Object

    All data will be passed to CKEDITOR.fileTools.fileLoader.responseData.

    Properties
    fileLoader : fileLoader

    A file loader instance.

    message : String

    The message from the server. Needs to be set in the listener — see the example above.

    fileName : String

    The file name on server. Needs to be set in the listener — see the example above.

    url : String

    The URL to the uploaded file. Needs to be set in the listener — see the example above.

  • floatingSpaceLayout( evt )

    since 4.5

    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
    Properties
    editor : editor

    The editor instance.

    data : Object
    Properties
    show : Boolean

    True if the float space should show up as a result of this event.

  • focus( evt )

    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
    Properties
    editor : editor

    The editor instance.

  • getData( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    dataValue : String

    The data that will be returned.

  • getSnapshot( evt )

    Internal event to perform the getSnapshot call.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • insertElement( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : element

    The element to insert.

  • insertHtml( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    mode : String

    The mode in which the data is inserted (see insertHtml).

    dataValue : String

    The HTML code to insert.

    [ range ] : range

    See insertHtml's range parameter.

  • insertText( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : String

    The text to insert.

  • instanceReady( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • key( evt )

    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
    Properties
    data : Object
    Properties
    keyCode : Number

    A number representing the key code (or a combination thereof). It is the sum of the current key code and the CKEDITOR.CTRL, CKEDITOR.SHIFT and CKEDITOR.ALT constants, if those are pressed.

    domEvent : event

    A keydown DOM event instance. Available since CKEditor 4.4.1.

    editor : editor

    This editor instance.

  • langLoaded( evt )

    since 3.6.1

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • loadSnapshot( evt )

    Internal event to perform the loadSnapshot call.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : String

    The data that will be used.

  • loaded( evt )

    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
    Properties
    editor : editor

    This editor instance.

  • lockSnapshot( evt )

    since 4.0

    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 recored (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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    [ dontUpdate ] : Boolean

    When set to true, the last snapshot will not be updated with the current content and selection. Read more in the CKEDITOR.plugins.undo.UndoManager.lock method.

    [ forceUpdate ] : Boolean

    When set to true, the last snapshot will always be updated with the current content and selection. Read more in the CKEDITOR.plugins.undo.UndoManager.lock method.

  • maximize( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Number

    Current state of the command. See CKEDITOR.TRISTATE_ON and CKEDITOR.TRISTATE_OFF.

  • menuShow( evt )

    Fired when a menu is shown.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : panel[]
  • mode( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • notificationHide( evt )

    since 4.5

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

    Notification which will be hidden.

    editor : editor

    The editor instance.

  • notificationShow( evt )

    since 4.5

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

    Notification which will be shown.

    editor : editor

    The editor instance.

  • notificationUpdate( evt )

    since 4.5

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

    Notification which will be updated. Note that it contains the data that has not been updated yet.

    options : Object

    Update options, see CKEDITOR.plugins.notification.update.

    editor : editor

    The editor instance.

  • paste( evt )

    since 3.1

    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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    type : String

    The type of data in data.dataValue. Usually 'html' or 'text', but for listeners with a priority smaller than 6 it may also be 'auto' which means that the content type has not been recognised yet (this will be done by the content type sniffer that listens with priority 6).

    dataValue : String

    HTML to be pasted.

    method : String

    Indicates the data transfer method. It could be drag and drop or copy and paste. Possible values: 'drop', 'paste'. Introduced in CKEditor 4.5.

    dataTransfer : dataTransfer

    Facade for the native dataTransfer object which provides access to various data types and files, and passes some data between linked events (like drag and drop). Introduced in CKEditor 4.5.

    [ dontFilter ] : Boolean

    Whether the paste filter should not be applied to data. This option has no effect when data.type equals 'text' which means that for instance CKEDITOR.config.forcePasteAsPlainText has a higher priority. Introduced in CKEditor 4.5.

    Defaults to false

  • pasteDialog( evt )

    private

    Internal event to open the Paste dialog window.

    This event was not available in 4.7.0-4.8.0 versions.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    [ data ] : Function

    Callback that will be passed to openDialog.

  • pasteDialogCommit( evt )

    private

    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
    Properties
    editor : editor

    This editor instance.

  • pasteFromWord( evt )

    since 4.6.0

    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
    Properties
    data : Object
    Properties
    dataValue : String

    Pasted content. Changes to this property will affect the pasted content.

  • pluginsLoaded( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • readOnly( evt )

    since 3.6

    Event fired after the readOnly property changes.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • removeFormatCleanup( evt )

    Fired after an element was cleaned by the removeFormat plugin.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    element : element

    The element that was cleaned up.

  • required( evt )

    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
    Properties
    editor : editor

    This editor instance.

  • resize( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object

    Available since CKEditor 4.5.

    Properties
    outerHeight : Number

    The height of the entire area that the editor covers.

    contentsHeight : Number

    Editable area height in pixels.

    outerWidth : Number

    The width of the entire area that the editor covers.

  • save( evt )

    since 4.2

    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
    Properties
    editor : editor

    This editor instance.

  • saveSnapshot( evt )

    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
    Properties
    editor : editor

    This editor instance.

  • selectionChange( evt )

    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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    selection : selection
    path : elementPath
  • setData( evt )

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

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    dataValue : String

    The data that will be used.

  • stylesSet( evt )

    since 4.1

    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
    Properties
    editor : editor

    This editor instance.

    styles : Array

    An array of styles definitions.

  • template( evt )

    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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    name : String

    The template name.

    source : String

    The source data for this template.

  • toDataFormat( evt )

    since 4.1

    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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    dataValue : String | fragment | element

    Output data to be prepared.

    context : String

    See CKEDITOR.htmlDataProcessor.toDataFormat The context argument.

    filter : Boolean

    See CKEDITOR.htmlDataProcessor.toDataFormat The filter argument.

    enterMode : Boolean

    See CKEDITOR.htmlDataProcessor.toDataFormat The enterMode argument.

  • toHtml( evt )

    since 4.1

    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
    Properties
    editor : editor

    This editor instance.

    data : Object
    Properties
    dataValue : String | fragment | element

    Input data to be purified.

    context : String

    See CKEDITOR.htmlDataProcessor.toHtml The context argument.

    fixForBody : Boolean

    See CKEDITOR.htmlDataProcessor.toHtml The fixForBody argument.

    dontFilter : Boolean

    See CKEDITOR.htmlDataProcessor.toHtml The dontFilter argument.

    filter : Boolean

    See CKEDITOR.htmlDataProcessor.toHtml The filter argument.

    enterMode : Boolean

    See CKEDITOR.htmlDataProcessor.toHtml The enterMode argument.

    [ protectedWhitespaces ] : Boolean

    See CKEDITOR.htmlDataProcessor.toHtml The protectedWhitespaces argument.

  • uiSpace( evt )

    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
    Properties
    data : Object
    Properties
    space : String

    The name of the space for which the event is fired.

    html : String

    HTML string which will be included in the given space.

  • unlockSnapshot( evt )

    since 4.0

    Unlocks the undo manager and updates the latest snapshot.

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance.

  • updateSnapshot( evt )

    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
    Properties
    editor : editor

    This editor instance.

  • widgetDefinition( evt )

    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
    Properties
    data : definition

    Widget definition.