Report an issue
Class

CKEDITOR

class singleton

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

Filtering

Config options

  • disableAutoInline : Boolean

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

    CKEDITOR.disableAutoInline = true;
    

    Defaults to false

  • replaceClass : String

    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

    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

    Creates an event class instance.

    Returns

    event
  • add( editor )

    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 )

    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

    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 )

    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

    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

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

    Register event handler under the capturing stage on supported target.

  • define( name, meta )

    Predefine some intrinsic properties on a specific event name.

    Parameters

    name : String

    The event name

    meta : Object
  • domReady()

    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 )

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

    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

    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.

  • getCss() → String

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

    Returns

    String

    A string containing CSS rules.

  • getTemplate( name )

    Retrieves a defined template created with addTemplate.

    Parameters

    name : String

    The template name.

  • getTemplates( name ) → collectionDefinition

    Gets templates' collection by its name.

    Parameters

    name : String

    Name of the templates' collection.

    Returns

    collectionDefinition
  • getUrl( resource ) → String

    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

    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

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

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

    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 )

    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

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

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

    CKEDITOR.event.on

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

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

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

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

    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 )

    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 )

    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 )

    Fired when a panel is added to the document.

    Parameters

    evt : eventInfo
  • currentInstance( evt )

    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 )

    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 )

    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 )

    Event fired when a CKEDITOR instance is destroyed.

    Parameters

    evt : eventInfo
  • instanceLoaded( evt )

    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 )

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

    Parameters

    evt : eventInfo
  • loaded( evt )

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

    Parameters

    evt : eventInfo
  • since 4.5.4

    log( evt )

    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 )

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

    Parameters

    evt : eventInfo