Latest revision as of 15:13, 2 June 2010

CONFIGURATION

CONFIGURATION OVERVIEW

Numerous configuration options included in CKEditor enable the developer to customize the appearance, features and behavior of the editor accordingly to end user needs.

Main configuration file is called config.js and is placed in the root of the CKEditor installation directory. The default configuration of CKEditor can be overridden either by editing the main configuration file or by changing the settings in separate file.

Editing the main configuration file is not recommended as the customized configuration settings will be lost every time the CKEditor is updated to a newer version. Default custom configuration file is called config.js and is placed in the root directory of CKEditor. If you want your settings to be stored in a different location, you need to point the CKeditor to use them. This is done by editing the main configuration file e.g. CKEDITOR.replace( 'myfiled', { customConfig : '/myconfig.js' } );

The above line will load myconfig.js configuration file. CKEditor recursively loads custom configuration files defined inside other custom configuration files.

In order to amend default settings of CKEditor, your custom configuration file needs to be edited to include required settings
e.g. config.defaultLanguage = 'de';

Custom configuration file does not need to contain all available settings, it is enough to include only the ones that you want to change.

NOTE: Do not delete nor move config.js file from _source\core directory!

CONFIGURATION OPTIONS

In this section are described configuration options and commands that need to be issued inside the custom configuration file.

No Custom Configuration File

To configure the editor not to load any custom configuration files, use the following setting:
CKEDITOR.config.customConfig = '';
All editor instances created after this command will not load custom configuration files.

baseHref

This setting is used to resolve relative and absolute URLs in the editor content:
config.baseHref = 'http://www.yourSite.com/path/';

contentsCss

This setting specifies the CSS file to be used to apply style to the contents:
config.contentsCss = '/css/mysitestyles.css';

Writing direction of the language

The default writing direction in CKEditor is Left-To-Right which is the most frequently used. To change this setting use the following command:
config.contentsLangDirection = 'rtl';

Default CKEditor language

Default language is used in case no language is set using config.language option and the editor is not able to use the user language.
In order to change default language use the following command:
config.defaultLanguage = 'it';

CKEditor language

This setting is used to set the CKEditor language. In case this option is not set, the editor will automatically try to load with user language if supported, otherwise the default language will be used. To set the language use the following command:
config.language = 'de';

enterMode

This setting is used to change editor’s behavior when the ENTER key is pressed. By default pressing ENTER creates a new paragraph. In order to change it the following command needs to be used:
config.enterMode = CKEDITOR.ENTER_BR;

The following values are accepted:

CKEDITOR.ENTER_P
CKEDITOR.ENTER_BR
CKEDITOR.ENTER_DIV

shiftEnterMode

This setting is used to change editor’s behavior when the SHIFT + ENTER keys are pressed. By default pressing it creates new line. In order to change it the following command needs to be used:
config.shiftEnterMode = CKEDITOR.ENTER_P;

The following values are accepted:

CKEDITOR.ENTER_P
CKEDITOR.ENTER_BR
CKEDITOR.ENTER_DIV

fullPage

This option is used to indicate whether the content of the edited area is a full web page or just its part. In order to change it use the following command:
config.fullPage = true;

docType

This option sets the Document Type Declaration to be used in the edited area. To change this setting use the following command:
config.docType = '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">';

Toolbar

toolbarLocation

This option sets the position of CKEditor toolbar ('top' by default). To change this setting use the following command:
config.toolbarLocation = 'bottom';

toolbar_Basic and toolbar_Full

These two features allow the developer to specify what options will be available on the toolbar for the end user. In order to change buttons on the toolbar use the following commands:
CKEDITOR.config.toolbar_Basic = [ [ 'Source', '-', 'Bold', 'Italic' ] ]; CKEDITOR.config.toolbar_Full = [ ['Source','-','Save','NewPage','Preview','-','Templates'], ['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'], '/', ['Bold','Italic','Underline','Strike','-','Subscript','Superscript'], ['Link','Unlink','Anchor'], '/', ['Styles','Format','Font','FontSize'], ];

The order of the buttons on the toolbar is determined by the order they appear in the above code. To divide the toolbar into sections, place all the functions for each section in separate square brackets []. To separate functions inside one section, the ‘-‘ sign should be used. To start a new line on the toolbar after chosen section, the ‘/’ sign should be used.

Toolbar Behavior

Both toolbar's type to be loaded on start-up and its behavior are specified in the toolbar plugin.

There are two types of toolbars specified in the toolbar plugin: toolbar_Basic and toolbar_Full. By default the toolbar_Full is loaded. To change this setting use the following command:
config.toolbar = 'Basic';

On editor's start-up the toolbar can appear either as expanded (default) or collapsed. To change this setting use the following command:
config.toolbarStartupExpanded = false;

It is also possible to specify whether the user can minimize the toolbar while working with editor (default) or not. To change this setting use the following command:
config.toolbarCanCollapse = false;

tabIndex

This option is used to specify how many “&nbsp” are inserted into HTML when TAB key is pressed and by default it is set to 0. To change editor’s behavior use the following command:
config.tabIndex = 1;

width and height

These two options are used to set the editor's width and height in CSS size format or in pixels. To change these settings use the following commands:
config.height = 220;
config.width = '100%';

skin

This option is used to specify the skin to be loaded. In order to change this setting use one of the following commands:

for skins located inside the ckeditor/_source/skins folder: config.skin = 'v2';
for skins located elsewhere, provide its name and a path separated by a comma: config.skin = 'myskin,/customstuff/myskin/';

plugins

This option is used to specify the list of plugins to be loaded and initialized. In order to change the list of plugins to be loaded use the following command:
config.plugins = 'basicstyles,button,htmldataprocessor,toolbar,wysiwygarea';

extraPlugins

This option is used to enable adding extra plugins to be loaded and initialized in the editor instance without a need to change the ‘plugins’ configuration. In order to change this setting use the following command:
config.extraPlugins = 'myfirstplugin,mysecondplugin';

@@ Line 1: / Line 1: @@
+<!-- Hi,
+I don't know where to put my 2c, sorry... But this "guide" does NOT look AT ALL like a wiki!
+Isn't this the "talk" page of the root folder ? Shouldn't the following text (called "configuration" go in the real "Configuration" page? It's really useful but barely visible to most.
+My advice : make red links, so people understand there should be something in place of the apparent void. The "Configuration" line in the menu isn't even a link ! And make the "edit this" CSS more visible, IMHO :hover isn't enough.
+In fact, you should create the complete "tree" with red links and give registered users the rights to edit them, didn't we solve a captcha? And vandalism is rather easy to fight...
+Anyway thanks for all and sorry again for the inappropriate place to post ; hope someone will read this!
+ps : this line is 9 months after. Nothing has changed. The "configuration" heading on the main page is still not a link.
+I'd really like to have the access statistics for this page, my bet is noone uses it because it's still not accessible.
+Is this mess ON PURPOSE so we have to pay for support?
+-->
 = CONFIGURATION  =
@@ Line 5: / Line 19: @@
 Numerous configuration options included in CKEditor enable the developer to customize the appearance, features and behavior of the editor accordingly to end user needs.
-Main configuration file is called config.js and is placed in the root of the CKEditor installation directory. The default configuration of CKEditor can be overridden either by editing the main configuration file or by changing the settings in separate file.
+Main configuration file is called <code>config.js</code> and is placed in the root of the CKEditor installation directory. The default configuration of CKEditor can be overridden either by editing the main configuration file or by changing the settings in separate file.
-Editing the main configuration file is not recommended as the customized configuration settings will be lost every time the CKEditor is updated to a newer version. Default custom configuration file is called ‘config.js’ and is placed in the root directory of CKEditor. If you want your settings to be stored in a different location, you need to point the CKeditor to use them. This is done by editing the main configuration file e.g. CKEDITOR.replace( 'myfiled', { customConfig&nbsp;: '/myconfig.js' } );
+Editing the main configuration file is not recommended as the customized configuration settings will be lost every time the CKEditor is updated to a newer version. Default custom configuration file is called <code>config.js</code> and is placed in the root directory of CKEditor. If you want your settings to be stored in a different location, you need to point the CKeditor to use them. This is done by editing the main configuration file e.g. <code>CKEDITOR.replace( 'myfiled', { customConfig&nbsp;: '/myconfig.js' } );</code>
-The above line will load myconfig.js configuration file. CKEditor recursively loads custom configuration files defined inside other custom configuration files.
+The above line will load <code>myconfig.js</code> configuration file. CKEditor recursively loads custom configuration files defined inside other custom configuration files.
-In order to amend default settings of CKEditor, your custom configuration file needs to be edited to include required settings<br>e.g. config.defaultLanguage = 'de';
+In order to amend default settings of CKEditor, your custom configuration file needs to be edited to include required settings<br>e.g. <code>config.defaultLanguage = 'de';</code>
 Custom configuration file does not need to contain all available settings, it is enough to include only the ones that you want to change.
-'''NOTE''': Do not delete nor move config.js file from _source\core directory!
+'''NOTE''': Do not delete nor move <code>config.js</code> file from <code>_source\core</code> directory!
-&nbsp;
 == CONFIGURATION OPTIONS  ==
-In this section configuration options and commands that need to be issued inside the custom configuration file are described.
+In this section are described configuration options and commands that need to be issued inside the custom configuration file.
 === No Custom Configuration File  ===
-To configure the editor not to load any custom configuration files, use the following setting:<br>CKEDITOR.config.customConfig = '';<br>All editor instances created after this command will not load custom configuration files.''
+To configure the editor not to load any custom configuration files, use the following setting:<br><code><nowiki>CKEDITOR.config.customConfig = '';</nowiki></code><br>All editor instances created after this command will not load custom configuration files.
 === baseHref  ===
-This setting is used to resolve relative and absolute URLs in the editor content:<br>config.baseHref = 'http://www.yourSite.com/path/';
+This setting is used to resolve relative and absolute URLs in the editor content:
+<br><code>config.baseHref = 'http://www.yourSite.com/path/'; </code>
 === contentsCss  ===
-This setting specifies the CSS file to be used to apply style to the contents:<br>config.contentsCss = '/css/mysitestyles.css';
+This setting specifies the CSS file to be used to apply style to the contents:
+<br><code>config.contentsCss = '/css/mysitestyles.css'; </code>
 === Writing direction of the language  ===
-The default writing direction in CKEditor is Left-To-Right which is the most frequently used. To change this setting use the following command:<br>config.contentsLangDirection = 'rtl';
+The default writing direction in CKEditor is Left-To-Right which is the most frequently used. To change this setting use the following command:
+<br><code>config.contentsLangDirection = 'rtl'; </code>
 === Default CKEditor language  ===
-Default language is used in case no language is set using config.language option and the editor is not able to use the user language.<br>In order to change default language use the following command:<br>config.defaultLanguage = 'it';
+Default language is used in case no language is set using config.language option and the editor is not able to use the user language.<br>In order to change default language use the following command:
+<br><code>config.defaultLanguage = 'it'; </code>
 === CKEditor language  ===
-This setting is used to set the CKEditor language. In case this option is not set, the editor will automatically try to load with user language if supported, otherwise the default language will be used. To set the language use the following command:<br>config.language = 'de';
+This setting is used to set the CKEditor language. In case this option is not set, the editor will automatically try to load with user language if supported, otherwise the default language will be used. To set the language use the following command:
+<br><code>config.language = 'de'; </code>
-=== Enter Mode  ===
+=== enterMode  ===
-This setting is used to change editor’s behavior when the ENTER key is pressed. By default pressing ENTER creates a new paragraph. In order to change it the following command needs to be used:<br>config.enterMode = CKEDITOR.ENTER_BR <br>The following values are accepted:
+This setting is used to change editor’s behavior when the ENTER key is pressed. By default pressing ENTER creates a new paragraph. In order to change it the following command needs to be used:
+<br><code>config.enterMode = CKEDITOR.ENTER_BR; </code>
-*CKEDITOR.ENTER_P
+The following values are accepted:
-*CKEDITOR.ENTER_BR
+*<code>CKEDITOR.ENTER_P </code>
-*CKEDITOR.ENTER_DIV
+*<code>CKEDITOR.ENTER_BR </code>
+*<code>CKEDITOR.ENTER_DIV</code>
-=== ShiftEnterMode  ===
+=== shiftEnterMode  ===
-This setting is used to change editor’s behavior when the SHIFT + ENTER keys are pressed. By default pressing it creates new line. In order to change it the following command needs to be used:<br>config.shiftEnterMode = CKEDITOR.ENTER_P
+This setting is used to change editor’s behavior when the SHIFT + ENTER keys are pressed. By default pressing it creates new line. In order to change it the following command needs to be used:
+<br><code>config.shiftEnterMode = CKEDITOR.ENTER_P; </code>
 The following values are accepted:
+*<code>CKEDITOR.ENTER_P </code>
+*<code>CKEDITOR.ENTER_BR </code>
+*<code>CKEDITOR.ENTER_DIV</code>
+=== fullPage  ===
+This option is used to indicate whether the content of the edited area is a full web page or just its part. In order to change it use the following command:
+<br><code>config.fullPage = true;</code>
+=== docType ===
-*CKEDITOR.ENTER_P
+This option sets the Document Type Declaration to be used in the edited area. To change this setting use the following command:
-*CKEDITOR.ENTER_BR
+<br><code>config.docType = '&amp;lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"&amp;gt;';</code>
-*CKEDITOR.ENTER_DIV
-=== fullPage  ===
+=== Toolbar ===
+==== toolbarLocation  ====
+This option sets the position of CKEditor toolbar ('top' by default). To change this setting use the following command:
+<br><code>config.toolbarLocation = 'bottom'; </code>
+==== toolbar_Basic and toolbar_Full  ====
+These two features allow the developer to specify what options will be available on the toolbar for the end user. In order to change buttons on the toolbar use the following commands:
+<br><code>CKEDITOR.config.toolbar_Basic = [ [ 'Source', '-', 'Bold', 'Italic' ] ];<br>CKEDITOR.config.toolbar_Full = [<br>['Source','-','Save','NewPage','Preview','-','Templates'],<br>['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'],<br>'/',<br>['Bold','Italic','Underline','Strike','-','Subscript','Superscript'],<br>['Link','Unlink','Anchor'],<br>'/',<br>['Styles','Format','Font','FontSize'],<br>]; </code>
+The order of the buttons on the toolbar is determined by the order they appear in the above code. To divide the toolbar into sections, place all the functions for each section in separate square brackets <code>[]</code>. To separate functions inside one section, the ‘<code>-</code>‘ sign should be used. To start a new line on the toolbar after chosen section, the ‘<code>/</code>’ sign should be used.
+==== Toolbar Behavior  ====
+Both toolbar's type to be loaded on start-up and its behavior are specified in the toolbar plugin.
+There are two types of toolbars specified in the toolbar plugin: toolbar_Basic and toolbar_Full. By default the toolbar_Full is loaded. To change this setting use the following command:
+<br><code>config.toolbar = 'Basic'; </code>
+On editor's start-up&nbsp;the toolbar can appear either as expanded (default) or collapsed. To change this setting use the following command:
+<br><code>config.toolbarStartupExpanded = false; </code>
+It is also possible to specify whether the user can minimize the toolbar while working with editor (default) or not. To change this setting use the following command:
+<br><code>config.toolbarCanCollapse = false;</code>
+=== tabIndex  ===
+This option is used to specify how many “&amp;nbsp” are inserted into HTML when TAB key is pressed and by default it is set to 0. To change editor’s behavior use the following command:
+<br><code>config.tabIndex = 1;</code>
+=== width and height  ===
+These two&nbsp;options are used to set the editor's width and height in CSS size format or in pixels. To change these settings use the following commands:
+<br><code>config.height = 220;</code>
+<br><code>config.width = '100%';</code>
+=== skin  ===
+This option is used to specify the skin to be loaded. In order to change this setting use one of the following commands:
-This option is used to indicate whether the content of the edited area is a full web page or just its part. In order to change it use the following command:<br>config.fullPage = true;<br>
+#for skins located inside the <code>ckeditor/_source/skins</code> folder:<code>&nbsp;config.skin = 'v2'; </code>
+#for skins located elsewhere, provide its name and a path separated by a comma:<code>&nbsp;config.skin = 'myskin,/customstuff/myskin/';</code>
-=== DocType<br> ===
+=== plugins  ===
-This option sets the Document Type Declaration to be used in the edited area. To change this setting use the following command:<br>config.docType = '&amp;lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"&amp;gt;';<br>
+This option is used to specify the list of plugins to be loaded and initialized. In order to change the list of plugins to be loaded use the following command:
+<br><code>config.plugins = 'basicstyles,button,htmldataprocessor,toolbar,wysiwygarea';</code>
-=== toolbarLocation ===
+=== extraPlugins  ===
-This option sets the position of CKEditor toolbar ('top' by default). To change this setting use the following command:<br>config.toolbarLocation = 'bottom';
+This option is used to enable adding extra plugins to be loaded and initialized in the editor instance without a need to change the ‘plugins’ configuration. In order to change this setting use the following command:
+<br><code>config.extraPlugins = 'myfirstplugin,mysecondplugin';</code>

CKSource

Login / Create Account

Page Tools

Developers Guide"