CKEDITOR.editor

class

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

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

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

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

Overrides: CKEDITOR.event.constructor
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:
- the getSelectedHtml method,
- the CKEDITOR.editable.extractHtmlFromRange method.
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:
- the extractSelectedHtml method,
- the CKEDITOR.editable.getHtmlFromRange method.
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:
- getData.
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.

CKEDITOR.event.on
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:
- static enterMode and shiftEnterMode values,
- dynamic activeEnterMode and activeShiftEnterMode values.
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:
- The paste event,
- The drop and dragend events,
- The CKEDITOR.plugins.clipboard.dataTransfer class.
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:
- The paste event,
- The drop and dragend events,
- The CKEDITOR.plugins.clipboard.dataTransfer class.
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:
- The paste event,
- The dragstart and dragend events,
- The CKEDITOR.plugins.clipboard.dataTransfer class.
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:
- the CKEDITOR.config.pasteFilter option,
- the drop event,
- the CKEDITOR.plugins.clipboard.dataTransfer class.
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:
- 1-4: Data is available in the original string format.
- 5: Data is initially filtered with regexp patterns and parsed to CKEDITOR.htmlParser.fragment CKEDITOR.htmlParser.element.
- 5-9: Data is available in the parsed format, but CKEDITOR.htmlDataProcessor.htmlFilter is not applied yet.
- 10: Data is filtered with CKEDITOR.htmlDataProcessor.htmlFilter.
- 11: Data is filtered with the {CKEDITOR.filter content filter} (on output the content filter makes only transformations, without filtering).
- 10-14: Data is available in the parsed format and CKEDITOR.htmlDataProcessor.htmlFilter has already been applied.
- 15: Data is written back to an HTML string.
- 15-*: Data is available in an HTML string.
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:
- 1-4: Data is available in the original string format.
- 5: Data is initially filtered with regexp patterns and parsed to CKEDITOR.htmlParser.fragment CKEDITOR.htmlParser.element.
- 5-9: Data is available in the parsed format, but CKEDITOR.htmlDataProcessor.dataFilter is not applied yet.
- 6: Data is filtered with the content filter.
- 10: Data is processed with CKEDITOR.htmlDataProcessor.dataFilter.
- 10-14: Data is available in the parsed format and CKEDITOR.htmlDataProcessor.dataFilter has already been applied.
- 15: Data is written back to an HTML string.
- 15-*: Data is available in an HTML string.
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.

CKEDITOR.editor

Filtering

Properties

activeEnterMode : NumberCKEDITOR.editor#activeEnterMode

activeFilter : filterCKEDITOR.editor#activeFilter

activeShiftEnterMode : NumberCKEDITOR.editor#activeShiftEnterMode

balloonToolbars : contextManagerCKEDITOR.editor#balloonToolbars

blockless : BooleanCKEDITOR.editor#blockless

config : configCKEDITOR.editor#config

container : elementCKEDITOR.editor#container

contextMenu : contextMenuCKEDITOR.editor#contextMenu

copyFormatting : stateCKEDITOR.editor#copyFormatting

dataProcessor : dataProcessorCKEDITOR.editor#dataProcessor

document : documentCKEDITOR.editor#document

element : elementCKEDITOR.editor#element

elementMode : NumberCKEDITOR.editor#elementMode

enterMode : NumberCKEDITOR.editor#enterMode

filter : filterCKEDITOR.editor#filter

focusManager : focusManagerCKEDITOR.editor#focusManager

id : StringCKEDITOR.editor#id

keystrokeHandler : keystrokeHandlerCKEDITOR.editor#keystrokeHandler

lang : ObjectCKEDITOR.editor#lang

langCode : StringCKEDITOR.editor#langCode

mode : StringCKEDITOR.editor#mode

name : StringCKEDITOR.editor#name

pasteFilter : filterCKEDITOR.editor#pasteFilter

plugins : ObjectCKEDITOR.editor#plugins

readOnly : BooleanCKEDITOR.editor#readOnly

shiftEnterMode : NumberCKEDITOR.editor#shiftEnterMode

status : StringCKEDITOR.editor#status

tabIndex : NumberCKEDITOR.editor#tabIndex

templates : ObjectCKEDITOR.editor#templates

title : String | BooleanCKEDITOR.editor#title

toolbar : ObjectCKEDITOR.editor#toolbar

ui : uiCKEDITOR.editor#ui

uploadRepository : uploadRepositoryCKEDITOR.editor#uploadRepository

widgets : repositoryCKEDITOR.editor#widgets

window : windowCKEDITOR.editor#window

Static properties

useCapture : BooleanCKEDITOR.editor#useCapture

Methods

constructor( [ instanceConfig ], [ element ], [ mode ] ) → editorCKEDITOR.editor#constructor

Parameters

Returns

addCommand( commandName, commandDefinition )CKEDITOR.editor#addCommand

Parameters

addContentsCss( cssPath )CKEDITOR.editor#addContentsCss

Parameters

addFeature( feature ) → BooleanCKEDITOR.editor#addFeature

Parameters

Returns

addMenuGroup( name, [ order ] )CKEDITOR.editor#addMenuGroup

Parameters

addMenuItem( name, definition )CKEDITOR.editor#addMenuItem

Parameters

addMenuItems( definitions )CKEDITOR.editor#addMenuItems

Parameters

addMode( mode, exec )CKEDITOR.editor#addMode

Parameters

addRemoveFormatFilter( func )CKEDITOR.editor#addRemoveFormatFilter

Parameters

applyStyle( style )CKEDITOR.editor#applyStyle

Parameters

attachStyleStateChange( style, callback )CKEDITOR.editor#attachStyleStateChange

Parameters

capture()CKEDITOR.editor#capture

checkDirty() → BooleanCKEDITOR.editor#checkDirty

Returns

createFakeElement( realElement, className, realElementType, isResizable ) → elementCKEDITOR.editor#createFakeElement

Parameters

Returns

createFakeParserElement( realElement, className, realElementType, isResizable ) → elementCKEDITOR.editor#createFakeParserElement

Parameters

Returns

createRange() → rangeCKEDITOR.editor#createRange

Returns

define( name, meta )CKEDITOR.editor#define

Parameters

destroy( [ noUpdate ] )CKEDITOR.editor#destroy

Parameters

`activeEnterMode : Number`

`activeFilter : filter`

`activeShiftEnterMode : Number`

`balloonToolbars : contextManager`

`blockless : Boolean`

`config : config`

`container : element`

`contextMenu : contextMenu`

`copyFormatting : state`

`dataProcessor : dataProcessor`

`document : document`

`element : element`

`elementMode : Number`

`enterMode : Number`

`filter : filter`

`focusManager : focusManager`

`id : String`

`keystrokeHandler : keystrokeHandler`

`lang : Object`

`langCode : String`

`mode : String`

`name : String`

`pasteFilter : filter`

`plugins : Object`

`readOnly : Boolean`

`shiftEnterMode : Number`

`status : String`

`tabIndex : Number`

`templates : Object`

`title : String | Boolean`

`toolbar : Object`

`ui : ui`

`uploadRepository : uploadRepository`

`widgets : repository`

`window : window`

`useCapture : Boolean`

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

`addCommand( commandName, commandDefinition )`

`addContentsCss( cssPath )`

`addFeature( feature ) → Boolean`

`addMenuGroup( name, [ order ] )`

`addMenuItem( name, definition )`

`addMenuItems( definitions )`

`addMode( mode, exec )`

`addRemoveFormatFilter( func )`

`applyStyle( style )`

`attachStyleStateChange( style, callback )`

`capture()`

`checkDirty() → Boolean`

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

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

`createRange() → range`

`define( name, meta )`

`destroy( [ noUpdate ] )`

`editable( [ elementOrEditable ] ) → element | null`

`elementPath( [ startNode ] ) → elementPath`

`execCommand( commandName, [ data ] ) → Boolean`

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

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

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

`focus()`

`forceNextSelectionCheck()`

`getClipboardData( callbackOrOptions, callback )`

`getColorFromDialog( callback, [ scope ] )`

`getCommand( commandName ) → command`

`getCommandKeystroke( command ) → Number | null`

`getData( internal ) → String`

`getMenuItem( name ) → Object`

`getResizable( forContents ) → element`

`getSelectedHtml( [ toString ] ) → documentFragment | String`

`getSelection( forceRealSelection ) → selection`

`getSnapshot() → String`

`getStylesSet( callback )`

`getUiColor() → String`

`hasListeners( eventName ) → Boolean`

`insertElement( element )`

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

`insertText( text )`

`loadSnapshot( snapshot )`

`lockSelection( [ sel ] ) → Boolean`