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

CKEDITOR

class singleton
See source

This is the API entry point. The entire CKEditor code runs under this object.

Filtering

Config options

  • disableAutoInline : Boolean

    See source

    Disables creating the inline editor automatically for elements with the contenteditable attribute set to true.

    CKEDITOR.disableAutoInline = true;

    Defaults to false

  • replaceClass : String

    See source

    The class name used to identify <textarea> elements to be replaced by CKEditor instances. Set it to empty/null to disable this feature.

    CKEDITOR.replaceClass = 'rich_editor';

    Defaults to 'ckeditor'

  • skinName : String

    See source

    The skin to load for all created instances, it may be the name of the skin folder inside the editor installation path, or the name and the path separated by a comma.

    Note: This is a global configuration that applies to all instances.

    CKEDITOR.skinName = 'moono';

CKEDITOR.skinName = 'myskin,/customstuff/myskin/';

    Defaults to 'moono-lisa'

Properties

Static properties

Methods

  • constructor() → event

    See source

    Creates an event class instance.

    Returns

    event

  • add( editor )

    See source

    Adds an editor instance to the global CKEDITOR object. This function is available for internal use mainly.

    Parameters

    editor : editor

    The editor instance to be added.

  • addCss( css )

    See source

    Adds CSS rules to be appended to the editor document. This method is mostly used by plugins to add custom styles to the editor document. For basic content styling the contents.css file should be used instead.

    Note: This function should be called before the creation of editor instances.

    // Add styles for all headings inside editable contents.
CKEDITOR.addCss( '.cke_editable h1,.cke_editable h2,.cke_editable h3 { border-bottom: 1px dotted red }' );

    Parameters

    css : String

    The style rules to be appended. CKEDITOR.config.contentsCss

  • addTemplate( name, source ) → template

    See source

    Adds a named CKEDITOR.template instance to be reused among all editors. This will return the existing one if a template with same name is already defined. Additionally, it fires the "template" event to allow template source customization.

    Parameters

    name : String

    The name which identifies a UI template.

    source : String

    The source string for constructing this template.

    Returns

    template

    The created template instance.

  • addTemplates( name, definition )

    See source

    Adds templates' collection to the list of all available templates.

    Parameters

    name : String

    Name of the templates' collection.

    definition : collectionDefinition

    Definition of templates' collection.

  • since 4.17.2

    appendTimestamp( resource ) → String

    See source

    Appends timestamp to the provided URL as querystring parameter ("t").

    Leaves the URL unchanged if it is a directory URL or it already contains querystring parameter.

    Parameters

    resource : String

    The resource URL to which the timestamp should be appended.

    Returns

    String

    The resource URL with cache key appended whenever possible.

  • appendTo( element, [ config ], [ data ] ) → editor | Function | null

    See source

    Creates a new editor instance at the end of a specific DOM element.

    <!DOCTYPE html>
    <html>
        <head>
            <meta charset="utf-8">
            <title>CKEditor</title>
            <!-- Make sure the path to CKEditor is correct. -->
        <script src="/ckeditor/ckeditor.js"></script>
    </head>
    <body>
        <div id="editorSpace"></div>
        <script>
            CKEDITOR.appendTo( 'editorSpace' );
        </script>
    </body>
</html>

    Since 4.17 this function also supports the Delayed Editor Creation feature allowing to postpone the editor initialization.

    Since 4.19 if the editor has been configured to use the Delayed Editor Creation feature and the editor has not been initialized yet, this function will return a handle allowing to cancel the interval set by the CKEDITOR.config.delayIfDetached and CKEDITOR.config.delayIfDetached_interval options.

    var cancelInterval = CKEDITOR.appendTo( 'editorSpace', {
    delayIfDetached: true,
    delayIfDetached_interval: 50 // Default value, you can skip that option.
} );

cancelInterval(); // Cancel editor initialization if needed.

    It is recommended to use this function to prevent potential memory leaks. Use it if you know that the editor host element will never be attached to the DOM. As an example, execute cancel handle in your component cleanup logic (e.g. onDestroy lifecycle methods in popular frontend frameworks).

    Read more about this feature in the documentation.

    Parameters

    element : Object | String

    The DOM element, its ID, or name.

    [ config ] : Object

    The specific configuration to apply to this editor instance. Configuration set here will override the global CKEditor settings (see CKEDITOR.config).

    [ data ] : String

    Since 3.3. Initial value for the instance.

    Returns

    editor | Function | null

    The editor instance or a cancelation function. If Delayed Editor Creation feature has not been set and element is missing in DOM, this function will return null.

  • capture()

    See source

    Register event handler under the capturing stage on supported target.

  • define( name, meta )

    See source

    Predefine some intrinsic properties on a specific event name.

    Parameters

    name : String

    The event name

    meta : Object

  • domReady()

    See source

    Specify a function to execute when the DOM is fully loaded.

    If called after the DOM has been initialized, the function passed in will be executed immediately.

  • editorConfig( config )

    See source

    Function called upon loading a custom configuration file that can modify the editor instance configuration (CKEDITOR.editor.config). It is usually defined inside the custom configuration files that can include developer defined settings.

    // This is supposed to be placed in the config.js file.
CKEDITOR.editorConfig = function( config ) {
    // Define changes to default configuration here. For example:
    config.language = 'fr';
    config.uiColor = '#AADC6E';
};

    Parameters

    config : config

    A configuration object containing the settings defined for a CKEDITOR.editor instance up to this function call. Note that not all settings may still be available. See Configuration Loading Order for details.

  • since 4.5.4

    error( errorCode, [ additionalData ] )

    See source

    Error reporting function. When verbosity has VERBOSITY_ERROR flag set, it fires event-log event with the type set to error. The fired event also contains the provided errorCode and additionalData.

    Parameters

    errorCode : String

    Error code describing the reported problem.

    [ additionalData ] : Object

    Additional data associated with the reported problem.

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

    See source

    Fires an specific event in the object. All registered listeners are called at this point.

    someObject.on( 'someEvent', function() { ... } );
someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );             // Both listeners are called.

someObject.on( 'someEvent', function( event ) {
    alert( event.data );                    // 'Example'
} );
someObject.fire( 'someEvent', 'Example' );

    Parameters

    eventName : String

    The event name to fire.

    [ data ] : Object

    Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.

    [ editor ] : editor

    The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.

    Returns

    Boolean | Object

    A boolean indicating that the event is to be canceled, or data returned by one of the listeners.

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

    See source

    Fires an specific event in the object, releasing all listeners registered to that event. The same listeners are not called again on successive calls of it or of fire.

    someObject.on( 'someEvent', function() { ... } );
someObject.fire( 'someEvent' );         // Above listener called.
someObject.fireOnce( 'someEvent' );     // Above listener called.
someObject.fire( 'someEvent' );         // No listeners called.

    Parameters

    eventName : String

    The event name to fire.

    [ data ] : Object

    Data to be sent as the CKEDITOR.eventInfo.data when calling the listeners.

    [ editor ] : editor

    The editor instance to send as the CKEDITOR.eventInfo.editor when calling the listener.

    Returns

    Boolean | Object

    A booloan indicating that the event is to be canceled, or data returned by one of the listeners.

  • getCss() → String

    See source

    Returns a string with all CSS rules passed to the addCss method.

    Returns

    String

    A string containing CSS rules.

  • getTemplate( name )

    See source

    Retrieves a defined template created with addTemplate.

    Parameters

    name : String

    The template name.

  • getTemplates( name ) → collectionDefinition

    See source

    Gets templates' collection by its name.

    Parameters

    name : String

    Name of the templates' collection.

    Returns

    collectionDefinition

  • getUrl( resource ) → String

    See source

    Gets the full URL for CKEditor resources. By default, URLs returned by this function contain a querystring parameter ("t") set to the timestamp value.

    It is possible to provide a custom implementation of this function by setting a global variable named CKEDITOR_GETURL. This global variable must be set before the editor script loading. If the custom implementation returns nothing (==null), the default implementation is used.

    // e.g. 'http://www.example.com/ckeditor/skins/default/editor.css?t=87dm'
alert( CKEDITOR.getUrl( 'skins/default/editor.css' ) );

// e.g. 'http://www.example.com/skins/default/editor.css?t=87dm'
alert( CKEDITOR.getUrl( '/skins/default/editor.css' ) );

// e.g. 'http://www.somesite.com/skins/default/editor.css?t=87dm'
alert( CKEDITOR.getUrl( 'http://www.somesite.com/skins/default/editor.css' ) );

    Parameters

    resource : String

    The resource whose full URL we want to get. It may be a full, absolute, or relative URL.

    Returns

    String

    The full URL.

  • hasListeners( eventName ) → Boolean

    See source

    Checks if there is any listener registered to a given event.

    var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
alert( someObject.hasListeners( 'someEvent' ) );    // true
alert( someObject.hasListeners( 'noEvent' ) );      // false

    Parameters

    eventName : String

    The event name.

    Returns

    Boolean

  • inline( element, [ instanceConfig ] ) → editor | Function | null

    See source

    Turns a DOM element with the contenteditable attribute set to true into a CKEditor instance. Check CKEDITOR.dtd.$editable for a list of allowed element names.

    Note: If the DOM element for which inline editing is being enabled does not have the contenteditable attribute set to true or the config.readOnly configuration option is set to true, the editor will start in read-only mode.

    <div contenteditable="true" id="content">...</div>
...
CKEDITOR.inline( 'content' );

    It is also possible to create an inline editor from the <textarea> element. If you do so, an additional <div> element with editable content will be created directly after the <textarea> element and the <textarea> element will be hidden.

    Since 4.17 this function also supports the Delayed Editor Creation feature allowing to postpone the editor initialization.

    Since 4.19 if the editor has been configured to use the Delayed Editor Creation feature and the editor has not been initialized yet, this function will return a handle allowing to cancel the interval set by the CKEDITOR.config.delayIfDetached and CKEDITOR.config.delayIfDetached_interval options.

    var cancelInterval = CKEDITOR.inline( 'editor', {
    delayIfDetached: true,
    delayIfDetached_interval: 50 // Default value, you can skip that option.
} );

cancelInterval(); // Cancel editor initialization if needed.

    It is recommended to use this function to prevent potential memory leaks. Use it if you know that the editor host element will never be attached to the DOM. As an example, execute cancel handle in your component cleanup logic (e.g. onDestroy lifecycle methods in popular frontend frameworks).

    Read more about this feature in the documentation.

    Parameters

    element : Object | String

    The DOM element or its ID.

    [ instanceConfig ] : Object

    The specific configurations to apply to this editor instance. See CKEDITOR.config.

    Returns

    editor | Function | null

    The editor instance or a cancellation function. If Delayed Editor Creation feature has not been set and element is missing in DOM, this function will return null.

  • inlineAll()

    See source

    Calls the CKEDITOR.inline() method for all page elements with the contenteditable attribute set to true that are allowed in the CKEDITOR.dtd.$editable object.

    Since 4.17 this function also supports the Delayed Editor Creation feature allowing to postpone the editor initialization. Read more about this feature in the documentation.

  • loadFullCore()

    See source

    Forces the full CKEditor core code, in the case only the basic code has been loaded (ckeditor_basic.js). This method self-destroys (becomes undefined) in the first call or as soon as the full code is available.

    // Check if the full core code has been loaded and load it.
if ( CKEDITOR.loadFullCore )
    CKEDITOR.loadFullCore();

  • loadTemplates( templateFiles, callback )

    See source

    Loads files that contains templates' collection definition.

    Parameters

    templateFiles : String[]

    Array of files' paths.

    callback : Function

    Function to be run after loading all files.

  • on( eventName, listenerFunction, [ scopeObj ], [ listenerData ], [ priority ] ) → Object

    See source

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

    someObject.on( 'someEvent', function() {
    alert( this == someObject );        // true
} );

someObject.on( 'someEvent', function() {
    alert( this == anotherObject );     // true
}, anotherObject );

someObject.on( 'someEvent', function( event ) {
    alert( event.listenerData );        // 'Example'
}, null, 'Example' );

someObject.on( 'someEvent', function() { ... } );                       // 2nd called
someObject.on( 'someEvent', function() { ... }, null, null, 100 );      // 3rd called
someObject.on( 'someEvent', function() { ... }, null, null, 1 );        // 1st called

    Note: CKEditor's event system has a limitation that one function cannot be used as a listener for the same event more than once. Hence, to reuse it with multiple listeners, it should be wrapped into additional wrapper function:

    function listener( evt ) { ... };

someObject.on( 'someEvent', function() {
    listener();
} );

someObject.on( 'someEvent', function( evt ) {
    listener( evt );
} );

    Parameters

    eventName : String

    The event name to which listen.

    listenerFunction : Function

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

    [ scopeObj ] : Object

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

    [ listenerData ] : Object

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

    [ priority ] : Number

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

    Defaults to 10

    Returns

    Object

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

  • once()

    See source

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

    CKEDITOR.event.on

  • removeAllListeners()

    See source

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

  • removeListener( eventName, listenerFunction )

    See source

    Unregisters a listener function from being called at the specified event. No errors are thrown if the listener has not been registered previously.

    var myListener = function() { ... };
someObject.on( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener called.
someObject.removeListener( 'someEvent', myListener );
someObject.fire( 'someEvent' );                 // myListener not called.

    Parameters

    eventName : String

    The event name.

    listenerFunction : Function

    The listener function to unregister.

  • replace( element, [ config ] ) → editor | Function | null

    See source

    Replaces a <textarea> or a DOM element (<div>) with a CKEditor instance. For textareas, the initial value in the editor will be the textarea value. For DOM elements, their innerHTML will be used instead. It is recommended to use <textarea> and <div> elements only.

    <textarea id="myfield" name="myfield"></textarea>
...
CKEDITOR.replace( 'myfield' );

var textarea = document.body.appendChild( document.createElement( 'textarea' ) );
CKEDITOR.replace( textarea );

    Since 4.17 this function also supports the Delayed Editor Creation feature allowing to postpone the editor initialization.

    Since 4.19 if the editor has been configured to use the Delayed Editor Creation feature and the editor has not been initialized yet, this function will return a handle allowing to cancel the interval set by the CKEDITOR.config.delayIfDetached and CKEDITOR.config.delayIfDetached_interval options.

    var cancelInterval = CKEDITOR.replace( 'editor', {
    delayIfDetached: true,
    delayIfDetached_interval: 50 // Default value, you can skip that option.
} );

cancelInterval(); // Cancel editor initialization if needed.

    It is recommended to use this function to prevent potential memory leaks. Use it if you know that the editor host element will never be attached to the DOM. As an example, execute cancel handle in your component cleanup logic (e.g. onDestroy lifecycle methods in popular frontend frameworks).

    Read more about this feature in the documentation.

    Parameters

    element : Object | String

    The DOM element (textarea), its ID, or name.

    [ config ] : Object

    The specific configuration to apply to this editor instance. Configuration set here will override the global CKEditor settings (see CKEDITOR.config).

    Returns

    editor | Function | null

    The editor instance or a cancellation function. If Delayed Editor Creation feature has not been set and element is missing in DOM, this function will return null.

  • replaceAll( [ className ], [ evaluator ] )

    See source

    Replaces all <textarea> elements available in the document with editor instances.

    // Replace all <textarea> elements in the page.
CKEDITOR.replaceAll();

// Replace all <textarea class="myClassName"> elements in the page.
CKEDITOR.replaceAll( 'myClassName' );

// Selectively replace <textarea> elements, based on a custom evaluation function.
CKEDITOR.replaceAll( function( textarea, config ) {
    // A function that needs to be evaluated for the <textarea>
    // to be replaced. It must explicitly return "false" to ignore a
    // specific <textarea>.
    // You can also customize the editor instance by having the function
    // modify the "config" parameter.
} );

// Full page example where three <textarea> elements are replaced.
<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8">
        <title>CKEditor</title>
        <!-- Make sure the path to CKEditor is correct. -->
        <script src="/ckeditor/ckeditor.js"></script>
    </head>
    <body>
        <textarea name="editor1"></textarea>
        <textarea name="editor2"></textarea>
        <textarea name="editor3"></textarea>
        <script>
            // Replace all three <textarea> elements above with CKEditor instances.
            CKEDITOR.replaceAll();
        </script>
    </body>
</html>

    Since 4.17 this function also supports the Delayed Editor Creation feature allowing to postpone the editor initialization. Read more about this feature in the documentation.

    Parameters

    [ className ] : String

    The <textarea> class name.

    [ evaluator ] : Function

    An evaluation function that must return true for a <textarea> to be replaced with the editor. If the function returns false, the <textarea> element will not be replaced.

  • since 4.5.4

    warn( errorCode, [ additionalData ] )

    See source

    Warning reporting function. When verbosity has the VERBOSITY_WARN flag set, it fires the event-log event with type set to warn. Fired event contains also provided errorCode and additionalData.

    Parameters

    errorCode : String

    Error code describing reported problem.

    [ additionalData ] : Object

    Additional data associated with reported problem.

  • private

    remove( editor )

    See source

    Removes an editor instance from the global CKEDITOR object. This function is available for internal use only. External code must use CKEDITOR.editor.destroy.

    Parameters

    editor : editor

    The editor instance to be removed.

Static methods

  • mixed static

    implementOn( targetObject )

    See source

    Implements the CKEDITOR.event features in an object.

    var myObject = { message: 'Example' };
CKEDITOR.event.implementOn( myObject );

myObject.on( 'testEvent', function() {
    alert( this.message );
} );
myObject.fire( 'testEvent' ); // 'Example'

    Parameters

    targetObject : Object

    The object into which implement the features.

Events

  • ariaWidget( evt )

    See source

    Fired when a panel is added to the document.

    Parameters

    evt : eventInfo

  • currentInstance( evt )

    See source

    Fired when the CKEDITOR.currentInstance object reference changes. This may happen when setting the focus on different editor instances in the page.

    var editor; // A variable to store a reference to the current editor.
CKEDITOR.on( 'currentInstance', function() {
    editor = CKEDITOR.currentInstance;
} );

    Parameters

    evt : eventInfo

  • dialogDefinition( evt )

    See source

    Event fired when a dialog definition is about to be used to create a dialog in an editor instance. This event makes it possible to customize the definition before creating it.

    Note that this event is called only the first time a specific dialog is opened. Successive openings will use the cached dialog, and this event will not get fired.

    Parameters

    evt : eventInfo

  • instanceCreated( evt )

    See source

    Event fired when a CKEDITOR instance is created, but still before initializing it. To interact with a fully initialized instance, use the instanceReady event instead.

    Parameters

    evt : eventInfo

  • instanceDestroyed( evt )

    See source

    Event fired when a CKEDITOR instance is destroyed.

    Parameters

    evt : eventInfo

  • instanceLoaded( evt )

    See source

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

    Parameters

    evt : eventInfo

  • instanceReady( evt )

    See source

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

    Parameters

    evt : eventInfo

  • loaded( evt )

    See source

    Fired when a CKEDITOR core object is fully loaded and ready for interaction.

    Parameters

    evt : eventInfo

  • since 4.5.4

    log( evt )

    See source

    Fired by warn and error methods. Default listener logs provided information to the console.

    This event can be used to provide a custom error/warning handler:

            CKEDTIOR.on( 'log', function( evt ) {
            // Cancel default listener.
            evt.cancel();
            // Log event data.
            console.log( evt.data.type, evt.data.errorCode, evt.data.additionalData );
        } );

    Parameters

    evt : eventInfo

  • reset( evt )

    See source

    Fired when the last instance has been destroyed. This event is used to perform global memory cleanup.

    Parameters

    evt : eventInfo