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

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

    See source
    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.

    See source
    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.

    See source

    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.

    See source

    Returns

    event

  • add( editor )

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

    See source

    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.

    See source

    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.

    See source

    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.

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

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

    See source
    <!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>

    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

    The editor instance created.

  • capture()

    Register event handler under the capturing stage on supported target.

    See source

  • define( name, meta )

    Predefine some intrinsic properties on a specific event name.

    See source

    Parameters

    name : String

    The event name

    meta : Object
    Properties
    [ errorProof ]

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

    Defaults to false

  • domReady()

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

    See source

    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.

    See source
    // 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.

  • error( errorCode, [ additionalData ] )

    since 4.5.4

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

    See source

    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.

    See source
    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.

    See source
    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.

    See source

    Returns

    String

    A string containing CSS rules.

  • getTemplate( name )

    Retrieves a defined template created with addTemplate.

    See source

    Parameters

    name : String

    The template name.

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

    See source

    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.

    See source
    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

    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.

    See source

    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 false, 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.

    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

    The editor instance created.

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

    See source

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

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

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

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

    See source
    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.

    See source

    CKEDITOR.event.on

  • removeAllListeners()

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

    See source

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

    See source
    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

    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.

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

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

    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

    The editor instance created.

  • replaceAll( [ className ], [ evaluator ] )

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

    See source
    // 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>

    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.

  • warn( errorCode, [ additionalData ] )

    since 4.5.4

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

    See source

    Parameters

    errorCode : String

    Error code describing reported problem.

    [ additionalData ] : Object

    Additional data associated with reported problem.

  • remove( editor )

    private

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

    See source

    Parameters

    editor : editor

    The editor instance to be removed.

Static methods

  • implementOn( targetObject )

    mixed static

    Implements the CKEDITOR.event features in an object.

    See source
    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.

    See source

    Parameters

    evt : eventInfo
    Properties
    data : Object

    The element wrapping the panel.

  • currentInstance( evt )

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

    See source
    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.

    See source

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

    The name of the dialog.

    definition : definition

    The dialog definition that is being loaded.

    dialog : dialog

    A dialog instance that the definition is loaded for. Introduced in CKEditor 4.13.0.

    editor : editor

    The editor instance that will use the dialog.

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

    See source

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    The editor instance that has been created.

  • instanceDestroyed( evt )

    Event fired when a CKEDITOR instance is destroyed.

    See source

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    The editor instance that has been destroyed.

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

    See source

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    This editor instance that has been loaded.

  • instanceReady( evt )

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

    See source

    Parameters

    evt : eventInfo
    Properties
    editor : editor

    The editor instance that has been created.

  • loaded( evt )

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

    See source

    Parameters

    evt : eventInfo

  • log( evt )

    since 4.5.4

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

    See source

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

    Log type. Can be error or warn.

    errorCode : String

    Error code describing the reported problem.

    [ additionalData ] : Object

    Additional data associated with this log event.

  • reset( evt )

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

    See source

    Parameters

    evt : eventInfo