Setting CKEditor Configuration

This website contains links to software which is either no longer maintained or will be supported only until the end of 2019 (CKFinder 2). For the latest documentation about current CKSource projects, including software like CKEditor 4/CKEditor 5, CKFinder 3, Cloud Services, Letters, Accessibility Checker, please visit the new documentation website.

If you look for an information about very old versions of CKEditor, FCKeditor and CKFinder check also the CKEditor forum, which was closed in 2015. If not, please head to StackOverflow for support.

(Using a Custom Configuration File: Minor rewriting)
 
(16 intermediate revisions by 4 users not shown)
Line 1: Line 1:
The editor comes with a rich set of configurations that makes it possible to customize its appearance, features and behavior. The main configuration file is named "config.js". You can find this file in the root of the CKEditor installation folder.  
+
{{#CUSTOMTITLE:Setting CKEditor Configuration}}
 +
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 <code>config.js</code>. This file can be found in the root of the CKEditor installation folder.  
  
 
== Available Configuration Options  ==
 
== Available Configuration Options  ==
 +
All available configuration options can be found in the [http://docs.cksource.com/ckeditor_api/index.html CKEditor JavaScript API] documentation. Refer to the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html CKEDITOR.config] object definition.
  
All available configuration options can be found inside our API documentation, inside the [http://docs.fckeditor.net/ckeditor_api/symbols/CKEDITOR.config.html CKEDITOR.config] object definition.  
+
== Defining Configuration In-Page  ==
 +
The best way to set the CKEditor configuration is in-page, when creating editor instances. This method lets you avoid modifying the original distribution files in the CKEditor installation folder, making the upgrade task easier.  
  
== Defining Configurations In-Page  ==
+
In-page settings can be passed to any of the editor instance creation functions, namely [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.html#.replace CKEDITOR.replace] and [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.html#.appendTo CKEDITOR.appendTo]. For example:  
 
+
<source lang="javascript">
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.
+
CKEDITOR.replace( 'editor1',
 
 
In-page settings can be passed to any of the editor instance creation functions, namely [http://docs.fckeditor.net/ckeditor_api/symbols/CKEDITOR.html#.replace CKEDITOR.replace] and [http://docs.fckeditor.net/ckeditor_api/symbols/CKEDITOR.html#.appendTo CKEDITOR.appendTo]. For example:  
 
<pre>CKEDITOR.replace( 'editor1',
 
 
     {
 
     {
         toolbar&nbsp;: 'basic',
+
         toolbar : 'Basic',
         uiColor&nbsp;: '# 9AB8F3'
+
         uiColor : '#9AB8F3'
 
     });
 
     });
</pre>  
+
</source>  
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.
+
Note that the configuration options are passed through a literal object definition (starting with a "<code>{</code>" symbol and ending with a "<code>}</code>" symbol). Because of this the proper syntax for each option is <code>(''configuration name'') : (''configuration value'')</code>. Be sure to not use the "equal" character (<code>=</code>) in place of the colon character (<code>:</code>).
 
 
== 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:  
+
== Using the config.js File ==
<pre>CKEDITOR.editorConfig = function( config )
+
CKEditor settings can also be configured by using the <code>config.js</code> file. By default this file is mostly empty. To change CKEditor configuration, add the settings that you want to modify to the <code>config.js</code> file. For example:  
 +
<source lang="javascript">
 +
CKEDITOR.editorConfig = function( config )
 
{
 
{
 
     config.language = 'fr';
 
     config.language = 'fr';
 
     config.uiColor = '#AADC6E';
 
     config.uiColor = '#AADC6E';
 
};
 
};
</pre>  
+
</source>
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.  
+
In order to apply the configuration settings, the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.html#.editorConfig CKEDITOR.editorConfig]</code> function must always be defined. The <code>config.js</code> file will be executed in the scope of your page, so you can also make references to variables defined in-page or even in other 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.  
+
== Using a Custom Configuration File ==
 +
Using a custom configuration file is another recommended method of setting CKEditor configuration. Instead of using the default <code>config.js</code> file, you can create a copy of that file anywhere in your website and simply point the editor instances to load it. The advantage of this approach is that in this way you can avoid changing the original file, which makes it easier 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 [http://docs.fckeditor.net/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig customConfig] setting when creating the editor instances. For example:  
+
Suppose you copied the <code>config.js</code> file to a folder named <code>custom</code> in the root of your website. You also renamed the file to <code>ckeditor_config.js</code>. At that point it is enough to only set the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig customConfig] configuration option when creating the editor instances to use the customized settings defined in the file. For example:  
<pre>CKEDITOR.replace( 'editor1',
+
<source lang="javascript">
 +
CKEDITOR.replace( 'editor1',
 
     {
 
     {
         customConfig&nbsp;: '/custom/ckeditor_config.js'
+
         customConfig : '/custom/ckeditor_config.js'
 
     });
 
     });
</pre>  
+
</source>
Your custom configuration file must look just like the default config.js file.  
+
The custom configuration file must look just like the default <code>config.js</code> 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:
 
  
#The editor instance is created. At this point all its default configurations are set.  
+
== Configuration Loading Order  ==
#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.  
+
You are not required to only use one of the above configuration options. The methods described above can be mixed and the configuration will be loaded properly. The following list presents the configuration loading order used when creating an editor instance:
#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.  
+
# An editor instance is created. At this point all its default configuration options are set.  
#Finally the settings defined "in-page" override the current instance settings (except customConfig, which has been used at point "1").
+
# If the <code>customConfig</code> setting has been set "in-page", that file is loaded, otherwise the default <code>config.js</code> file is loaded. All settings in the custom configuration file override current instance settings.  
 +
# If the settings loaded in step 2 also define a new <code>customConfig</code> value, another custom configuration file is loaded and its settings override current instance settings. This happens recursively for all files until no <code>customConfig</code> is defined.  
 +
# Finally the settings defined "in-page" override current instance settings (except <code>customConfig</code>, which has been used in step 1).
  
 
== Avoiding Loading External Settings Files ==
 
== 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, you need to set the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig customConfig] setting to an empty string. For example:  
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 [http://docs.fckeditor.net/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig customConfig] setting to an empty string. For example:  
+
<source lang="javascript">
<pre>CKEDITOR.replace( 'editor1',
+
CKEDITOR.replace( 'editor1',
 
     {
 
     {
         customConfig&nbsp;: ''
+
         customConfig : ''
 
     });
 
     });
</pre>  
+
</source>
This setting is definitely recommended if you are not setting configurations in the config.js file nor a custom configuration file.
+
This setting is definitely recommended, if you are not setting the configuration in the <code>config.js</code> file nor a custom configuration file.
 +
 
 +
== Mapping CKEditor and FCKeditor Configuration Settings ==
 +
If you moved to CKEditor from its predecessor, FCKeditor, you might be used to setting the configuration in the FCKeditor way. To make it easier for you to upgrade to the new editor line we have prepared a mapping between configuration settings available in [[FCKeditor_2.x/Developers_Guide|FCKeditor 2.x]] and CKEditor 3.x. A full listing [[CKEditor_3.x/Developers_Guide/FCKeditor_CKEditor_Configuration_Mapping|can be found here]].

Latest revision as of 15:44, 8 March 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 in the CKEditor JavaScript API documentation. Refer to the CKEDITOR.config object definition.

Defining Configuration In-Page

The best way to set the CKEditor configuration is in-page, when creating editor instances. This method lets you avoid modifying 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 configuration options are passed through a literal object definition (starting with a "{" symbol and ending with a "}" symbol). Because of this the proper syntax for each option is (configuration name) : (configuration value). Be sure to not use the "equal" character (=) in place of the colon character (:).

Using the config.js File

CKEditor settings can also be configured by using the config.js file. By default this file is mostly empty. To change CKEditor configuration, add the settings that you want to modify to the config.js file. For example:

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

In order to apply the configuration settings, the CKEDITOR.editorConfig function must always be defined. The config.js file will be executed in the scope of your page, so you can also make references to variables defined in-page or even in other JavaScript files.

Using a Custom Configuration File

Using a custom configuration file is another recommended method of setting CKEditor configuration. Instead of using the default config.js file, you can create a copy of that file anywhere in your website and simply point the editor instances to load it. The advantage of this approach is that in this way you can avoid changing the original file, which makes it easier to upgrade CKEditor later by simply overwriting all files.

Suppose you copied the config.js file to a folder named custom in the root of your website. You also renamed the file to ckeditor_config.js. At that point it is enough to only set the customConfig configuration option when creating the editor instances to use the customized settings defined in the file. For example:

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

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

Configuration Loading Order

You are not required to only use one of the above configuration options. The methods described above can be mixed and the configuration will be loaded properly. The following list presents the configuration loading order used when creating an editor instance:

  1. An editor instance is created. At this point all its default configuration options 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 the custom configuration file override current instance settings.
  3. If the settings loaded in step 2 also define a new customConfig value, another custom configuration file is loaded and its settings override current instance settings. This happens recursively for all files until no customConfig is defined.
  4. Finally the settings defined "in-page" override current instance settings (except customConfig, which has been used in step 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, you need 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 the configuration in the config.js file nor a custom configuration file.

Mapping CKEditor and FCKeditor Configuration Settings

If you moved to CKEditor from its predecessor, FCKeditor, you might be used to setting the configuration in the FCKeditor way. To make it easier for you to upgrade to the new editor line we have prepared a mapping between configuration settings available in FCKeditor 2.x and CKEditor 3.x. A full listing can be found here.

This page was last edited on 8 March 2011, at 15:44.