CKEDITOR.editor

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.

Available since: 4.3

See the activeEnterMode property.

Available since: 4.3

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.

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'

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'

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.

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

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.

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

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.

Available since: 4.3

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.

Available since: 4.1

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.

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

Controls keystroke typing in this editor instance.

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)

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'

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'

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.

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.

Available since: 4.5

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

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

Available since: 3.6

See the enterMode property.

Available since: 4.3

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'

Available since: 4.1

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

Contains all UI templates created for this editor instance.

Defaults to: {}

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.

Available since: 4.2

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.

The namespace containing UI features related to this editor instance.

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' );

Available since: 4.5

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

Available since: 4.3

The window instance related to the document property.

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

See the document property documentation.

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.

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 + '"!' );
        }
    } );

Parameters

• commandName : String

  The indentifier name of the command.

• commandDefinition : CKEDITOR.commandDefinition

  The command definition.

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' );

Available since: 4.4

Parameters

• cssPath : String

  The path to the stylesheet file which should be added.

Shorthand for CKEDITOR.filter.addFeature.

Available since: 4.1

Parameters

• feature : CKEDITOR.feature

  See CKEDITOR.filter.addFeature.

Returns

• Boolean

  See CKEDITOR.filter.addFeature.

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

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

  Defaults to: 100

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.

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.

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.

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

Available since: 3.3

Parameters

• func : Function

  The function to be called, which will be passed a {CKEDITOR.dom.element} element to test.

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

Parameters

• style : CKEDITOR.style

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 : CKEDITOR.style

  The style to be watched.

• callback : Function

  The function to be called.

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.

Parameters

• realElement : Object
• className : Object
• realElementType : Object
• isResizable : Object

Parameters

• realElement : Object
• className : Object
• realElementType : Object
• isResizable : Object

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

Returns

• CKEDITOR.dom.range

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

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

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

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

Parameters

• elementOrEditable : CKEDITOR.dom.element/CKEDITOR.editable

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

Returns an element path for the selection in the editor.

Parameters

• startNode : CKEDITOR.dom.node (optional)

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

Returns

• CKEDITOR.dom.elementPath

Executes a command associated with the editor.

editorInstance.execCommand( 'bold' );

Parameters

• commandName : String

  The indentifier name of the command.

• data : Object (optional)

  The data to be passed to the command.

Returns

• Boolean

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

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.

Available since: 4.5

Parameters

• toString : Boolean (optional)

  If true, then stringified HTML will be returned.

• removeEmptyBlock : Boolean (optional)

  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

• CKEDITOR.dom.documentFragment/String/null

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

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

editor.getClipboardData( { title: 'Get my data' }, function( data ) {
    if ( data )
        alert( data.type + ' ' + data.dataValue );
} );

Parameters

• options : Object
  • title : String (optional)

    The title of the paste dialog window.

• callback : Function

  A function that will be executed with data.type and data.dataValue or null if none of the capturing methods succeeded.

Open up color dialog and to receive the selected color.

Parameters

• callback : Function

  The callback when color dialog is closed

  Parameters

  • color : String

    The color value received if selected on the dialog.

• scope : Object (optional)

  The scope in which the callback will be bound.

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

• CKEDITOR.command

  The command object identified by the provided name.

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.

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

Parameters

• name : String

  The name of the desired menu item.

Returns

• Object

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

• CKEDITOR.dom.element

  The resizable element.

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.

Available since: 4.5

Parameters

• toString : Boolean (optional)

  If true, then stringified HTML will be returned.

Returns

• CKEDITOR.dom.documentFragment/String

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

• CKEDITOR.dom.selection

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

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

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.

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.

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 : CKEDITOR.dom.element

  The element to be inserted into the editor.

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

  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 : CKEDITOR.dom.range (optional)

  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.

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.

Available since: 3.5

Parameters

• text : String

  Text to be inserted into the editor.

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

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 : CKEDITOR.dom.selection (optional)

  Specify the selection to be locked.

Returns

• Boolean

  true if selection was locked.

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

• CKEDITOR.dialog

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

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

  Popup window width.

  Defaults to: '80%'

• height : Number/String (optional)

  Popup window height.

  Defaults to: '70%'

• options : String (optional)

  Popup window features.

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

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

Available since: 3.6.1

Parameters

• name : String

  The name of the desired menu item.

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

Parameters

• style : CKEDITOR.style

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

Resets the undo stack.

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

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

  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.

Parameters

• fakeElement : Object

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

Parameters

• checkNow : Boolean (optional)

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

  Defaults to: false

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.

Available since: 4.3

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.

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

Available since: 4.3

Parameters

• filter : CKEDITOR.filter

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

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 (optional)
  • internal : Boolean (optional)

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

    Defaults to: false

  • callback : Function (optional)

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

  • noSnapshot : Boolean (optional)

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

    Defaults to: false

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.

Available since: 4.0

Parameters

• keystroke : Number/Array

  A keystroke or an array of keystroke definitions.

• behavior : String/Boolean (optional)

  A command to be executed on the keystroke.

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

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

• callback : Function (optional)

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

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.

Available since: 3.6

Parameters

• isReadOnly : Boolean (optional)

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

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.

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.

Available since: 4.5

Parameters

• message : String

  The message displayed in the notification.

• type : String (optional)

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

  Defaults to: 'info'

• progressOrDuration : Number (optional)

  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

• CKEDITOR.plugins.notification

  Created and shown notification.

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

Parameters

• restore : Boolean (optional)

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

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

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

Available since: 4.3

Parameters

• evt : CKEDITOR.eventInfo

Event fired after the command execution when execCommand is called.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • name : String

      The command name.

    • commandData : Object

      The data sent to the command.

    • command : CKEDITOR.command

      The command itself.

    • returnValue : Object

      The value returned by the command execution.

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

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • data : Object
    • intoRange : CKEDITOR.dom.range (optional)

      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.

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 : CKEDITOR.eventInfo

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • dataValue : String

      The data that has been set.

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.

Available since: 3.5.3

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance. CKEDITOR.editor.beforeUndoImage

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;

Available since: 4.4.3

Parameters

• evt : CKEDITOR.eventInfo
  • label : String

    The label to be used.

Fired when some elements are added to the document.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : CKEDITOR.dom.element

    The element being added.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • 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.

Event fired before the command execution when execCommand is called.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • name : String

      The command name.

    • commandData : Object

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

    • command : CKEDITOR.command

      The command itself.

Internal event to get the current data.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo

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

Available since: 3.5.3

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : String

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

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.

Available since: 3.5.3

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance. CKEDITOR.editor.afterUndoImage

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    The editor instance.

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

Available since: 4.2

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : String

    The direction in the current position.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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.

Available since: 4.3

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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

Available since: 4.1

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

Event fired when a dialog is hidden.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : CKEDITOR.dialog

    The hidden dialog instance.

Event fired when a dialog is shown.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : CKEDITOR.dialog

    The opened dialog instance.

Fired when the language direction of an element is changed.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • node : CKEDITOR.dom.node

      The element that is being changed.

    • dir : String

      The new direction.

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 : CKEDITOR.eventInfo
  • data : Object
    • element : CKEDITOR.dom.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.

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.

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • $ : Object

      Native dragend event.

    • target : CKEDITOR.dom.node

      Drag target.

    • dataTransfer : CKEDITOR.plugins.clipboard.dataTransfer

      DataTransfer facade.

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.

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • $ : Object

      Native dragstart event.

    • target : CKEDITOR.dom.node

      Drag target.

    • dataTransfer : CKEDITOR.plugins.clipboard.dataTransfer

      DataTransfer facade.

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.

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • $ : Object

      Native drop event.

    • target : CKEDITOR.dom.node

      Drop target.

    • dataTransfer : CKEDITOR.plugins.clipboard.dataTransfer

      DataTransfer facade.

    • dragRange : CKEDITOR.dom.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 : CKEDITOR.dom.range

      Drop range, lets you manipulate the drop range.

Fired when the contents of the elementsPath are changed.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • space : CKEDITOR.dom.element

      The elementsPath container.

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

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • data : Object
    • fileLoader : CKEDITOR.fileTools.fileLoader

      File loader instance.

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. To learn more refer to the Uploading Dropped or Pasted Files article.

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • data : Object
    • fileLoader : CKEDITOR.fileTools.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.

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

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    The editor instance.

  • data : Object
    • show : Boolean

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

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    The editor instance.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • dataValue : String

      The data that will be returned.

Internal event to perform the getSnapshot call.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : CKEDITOR.dom.element

    The element to insert.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • mode : String

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

    • dataValue : String

      The HTML code to insert.

    • range : CKEDITOR.dom.range (optional)

      See insertHtml's range parameter.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : String

    The text to insert.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo
  • data : Object
    • 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 : CKEDITOR.dom.event

      A keydown DOM event instance. Available since CKEditor 4.4.1.

  • editor : CKEDITOR.editor

    This editor instance.

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

Available since: 3.6.1

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

Internal event to perform the loadSnapshot call.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : String

    The data that will be used.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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.

Available since: 4.0

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • dontUpdate : Boolean (optional)

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

      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.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Number

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

Fired when a menu is shown.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : CKEDITOR.ui.panel[]

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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.

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • data : Object
    • notification : CKEDITOR.plugins.notification

      Notification which will be hidden.

  • editor : CKEDITOR.editor

    The editor instance.

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.

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • data : Object
    • notification : CKEDITOR.plugins.notification

      Notification which will be shown.

  • editor : CKEDITOR.editor

    The editor instance.

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.

Available since: 4.5

Parameters

• evt : CKEDITOR.eventInfo
  • data : Object
    • notification : CKEDITOR.plugins.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 : CKEDITOR.editor

    The editor instance.

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.

Available since: 3.1

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • 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 : CKEDITOR.plugins.clipboard.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 (optional)

      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

Internal event to open the Paste dialog window.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Function (optional)

    Callback that will be passed to openDialog.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

Event fired after the readOnly property changes.

Available since: 3.6

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

Fired after an element was cleaned by the removeFormat plugin.

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • element : CKEDITOR.dom.element

      The element that was cleaned up.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object

    Available since CKEditor 4.5.

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

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

Available since: 4.2

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • selection : CKEDITOR.dom.selection
    • path : CKEDITOR.dom.elementPath

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

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • dataValue : String

      The data that will be used.

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.

Available since: 4.1

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • styles : Array

    An array of styles definitions.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • name : String

      The template name.

    • source : String

      The source data for this template.

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

Available since: 4.1

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • dataValue : String/CKEDITOR.htmlParser.fragment/CKEDITOR.htmlParser.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.

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 {CKEDITOR.filter 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 );

Available since: 4.1

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

  • data : Object
    • dataValue : String/CKEDITOR.htmlParser.fragment/CKEDITOR.htmlParser.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 (optional)

      See CKEDITOR.htmlDataProcessor.toHtml The protectedWhitespaces argument.

Unlocks the undo manager and updates the latest snapshot.

Available since: 4.0

Parameters

• evt : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo
  • editor : CKEDITOR.editor

    This editor instance.

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 : CKEDITOR.eventInfo
  • data : CKEDITOR.plugins.widget.definition

    Widget definition.