Revision as of 08:06, 13 January 2011

CKEditor comes with a rich set of configuration options that make it possible to customize its appearance, features, and behavior. The main configuration file is named config.js. This file can be found in the root of the CKEditor installation folder.

Available Configuration Options

All available configuration options can be found inside our API documentation, inside the CKEDITOR.config object definition.

Defining Configurations In-Page

The best way to set your configurations is in-page, when creating editor instances. In this way you avoid touching the original distribution files in the CKEditor installation folder, making the upgrade task easier.

In-page settings can be passed to any of the editor instance creation functions, namely CKEDITOR.replace and CKEDITOR.appendTo. For example:

CKEDITOR.replace( 'editor1',
    {
        toolbar : 'Basic',
        uiColor : '#9AB8F3'
    });

Note that the configurations are passed through a literal object definition (starting with "{" and ending with "}"). Because of this, the proper syntax for each option is (configuration name) + ":" + (configuration value). Be sure to not use the equal sign ("=") sign.

Using the config.js File

You can also place your settings inside the config.js file also. You will note that the file is mostly empty by default. You simply need to add the configurations that you want to change. For example:

CKEDITOR.editorConfig = function( config )
{
    config.language = 'fr';
    config.uiColor = '#AADC6E';
};

The above CKEDITOR.editorConfig function definition must be always defined so the settings can be applied. This configuration file will be executed in your page scope, so you can also make references to variables defined in-page or even in another JavaScript files.

Using a Custom Configuration File

This is another recommended way to set your configurations. Instead of using the default config.js file, you create a copy of that file anywhere in your web site and simply point your editor instances to load it. The advantage of it is that you avoid changing the original file, making it easy to upgrade CKEditor later, by simply overwriting all files.

Suppose you have copied config,js inside a folder named "custom" in the root of your web site. You have also renamed the file to "ckeditor_config.js". At that point, you must only set the customConfig setting when creating the editor instances. For example:

CKEDITOR.replace( 'editor1',
    {
        customConfig : '/custom/ckeditor_config.js'
    });

Your custom configuration file must look just like the default config.js file.

Configurations Overload Order

You're not required to use only one of the above configuration options. You can mix all of them, and the configurations will be overloaded properly. The following is configurations loading order when creating an editor instance:

1. The editor instance is created. At this point all its default configurations are set.
2. If the customConfig setting has been set "in-page", that file is loaded, otherwise the default config.js file is loaded. All settings in this file override the current instance settings.
3. If the settings loaded in point "2" also define a new customConfig value, this new file is loaded and its settings overload the current instance settings. This happens recursively for all files until no customConfig is defined.
4. Finally the settings defined "in-page" override the current instance settings (except customConfig, which has been used at point "1").

Avoiding Loading External Settings Files

It is also possible to completely avoid loading an external configuration file, reducing the number of files loaded. To do that, it's enough to set the customConfig setting to an empty string. For example:

CKEDITOR.replace( 'editor1',
    {
        customConfig : ''
    });

This setting is definitely recommended if you are not setting configurations in the config.js file nor a custom configuration file.