CKSource Docs - User contributions [en]

CKEditor 3.x/Developers Guide/jQuery Adapter

2010-01-20T09:04:30Z

TobiaszCudnik:

CKEditor offers native jQuery integration through its jQuery Adapter (a jQuery plugin basically). It provides deep integration of CKEditor into jQuery, using its native features.

== Creating editor instances ==

To create editor instances, other than the usual CKEditor core script, you need to load the jQuery Adapter file in the page, in the following order:

<source language="html"><script type="text/javascript" src="/ckeditor/ckeditor.js"></script>
<script type="text/javascript" src="/ckeditor/adapters/jquery.js"></script></source>

At this point, any textarea, p or div element can be transformed into a rich text editor by simply using the ckeditor() method:
<source language="js">$( 'textarea.editor' ).ckeditor();</source>
jQuery chaining can also be used:
<source language="js">$( '.section-x' )
.find( 'textarea.editor' )
.ckeditor()
.end()
.find( 'a' )
.addClass( 'mylink' )
.end();</source>

The ckeditor() is the main method in the jQuery adapter. It accepts two optional parameters:
* A '''callback function''' to be execute when the editor is ready.
* '''Configuration options''' specific to the created editor instance.

The [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html configurations options] are passed through a simple object containing properties, each one related to a specific editor setting.</p>
<source language="js">$('.jquery_ckeditor')
.ckeditor( function() { /* callback code */ }, { skin : 'office2003' } );
.ckeditor( callback2 );</source>

Code above won't create 2 editors - it will discover that one is already during creation and wait with the second callback. Each of those callbacks will be executed in context of the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object (so "this" will be the editor) and the DOM element object will be passed as parameter.

== Code interaction with editor instances==
As soon as an editor instance is ready (after the above callback call), the ckeditorGet() method can then be used to retrieve a [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object that represents an editor instance. For example:
<source language="js">var editor = $('.jquery_ckeditor').ckeditorGet();
alert( editor.checkDirty() );
</source>

Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the dedicated val() method:
<source language="js">// Get the editor data.
var data = $( 'textarea.editor' ).val();
// Set the editor data.
$( 'textarea.editor' ).val( 'my new content' );</source>

This feature can be disabled by setting CKEDITOR.config.jqueryOverrideVal to false, before loading the adapter code.

For textareas, the editor will automatically return it's content back to the form when it is submitted. CKEditor also works with the official [http://jquery.malsup.com/form/ jQuery Form Plugin] for AJAX based forms. It doesn't require anything from the developer side.

== Events handling ==
Although CKEditor uses its own event system, there are four main events which we're exposing to the jQuery event system. All events use the event namespace, which is simply named ".ckeditor".

The following events are available:
* <strong>instanceReady.ckeditor</strong>: fired when the editor is created, but before any callback being passed to the ckeditor() method.
* <strong>setData.ckeditor</strong>: fired when data is set into the editor.
* <strong>getData.ckeditor</strong>: fired when data is fetched from the editor. The current editor data is also passed in the arguments.
* <strong>destroy.ckeditor</strong>: fired when the editor gets destroyed. It can be used, for example, to execute some cleanup on the page.

The editor instance is always passed as the first data argument for the listener. Both getData and setData are often used internally so listening to them should be done with care.

jQuery events DO bubble up through the DOM, so they can be listened selectively on certain parts of the document.

CKEditor 3.x/Developers Guide/jQuery Adapter

2010-01-19T15:04:17Z

TobiaszCudnik:

The CKEditor jQuery Adapter provides deep integration into the jQuery JavaScript Library of the CKEditor, using native library's features.

== Creating editor instances ==
To create editor instances, other than the usual CKEditor core script, you need to load the jQuery Adapter file in the page, in the following order:

<source language="html"><script type="text/javascript" src="/ckeditor/ckeditor.js"></script>
<script type="text/javascript" src="/ckeditor/adapters/jquery.js"></script></source>

At this point, any textarea, p or div element can be transformed into a rich text editor by simply using the ckeditor() method:
<source language="js">$( 'textarea.editor' ).ckeditor();</source>
jQuery chaining can also be used:
<source language="js">$( '.section-x' )
.find( 'textarea.editor' )
.ckeditor()
.end()
.find( 'a' )
.addClass( 'mylink' )
.end();</source>

The ckeditor() is the main method in the jQuery adapter. It accepts two optional parameters:
* A '''callback function''' to be execute when the editor is ready.
* '''Configuration options''' specific to the created editor instance.

The [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html configurations options] are passed through a simple object containing properties, each one related to a specific editor setting.</p>
<source language="js">$('.jquery_ckeditor')
.ckeditor( function() { /* callback code */ }, { skin : 'office2003' } );
.ckeditor( callback2 );</source>

Code above won't create 2 editors - it will discover that one is already during creation and wait with the second callback. Each of those callbacks will be executed in context of the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object (so "this" will be the editor) and the DOM element object will be passed as parameter.

== Code interaction with editor instances==
As soon as an editor instance is ready (after the above callback call), the ckeditorGet() method can then be used to retrieve a [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object that represents an editor instance. For example:
<source language="js">var editor = $('.jquery_ckeditor').ckeditorGet();
alert( editor.checkDirty() );
</source>

Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the dedicated val() method:
<source language="js">// Get the editor data.
var data = $( 'textarea.editor' ).val();
// Set the editor data.
$( 'textarea.editor' ).val( 'my new content' );</source>

This feature can be disabled by setting CKEDITOR.config.jqueryOverrideVal to false, before loading the adapter code.

For textareas, the editor will automatically return it's content back to the form when it is submitted. CKEditor also works with the official [http://jquery.malsup.com/form/ jQuery Form Plugin] for AJAX based forms. It doesn't require anything from the developer side.

== Events handling ==
Although CKEditor uses its own event system, there are four main events which we're exposing to the jQuery event system. All events use the event namespace, which is simply named ".ckeditor".

The following events are available:
* <strong>instanceReady.ckeditor</strong>: fired when the editor is created, but before any callback being passed to the ckeditor() method.
* <strong>setData.ckeditor</strong>: fired when data is set into the editor.
* <strong>getData.ckeditor</strong>: fired when data is fetched from the editor. The current editor data is also passed in the arguments.
* <strong>destroy.ckeditor</strong>: fired when the editor gets destroyed. It can be used, for example, to execute some cleanup on the page.

The editor instance is always passed as the first data argument for the listener. Both getData and setData are often used internally so listening to them should be done with care.

jQuery events DO bubble up through the DOM, so they can be listened selectively on certain parts of the document.

CKEditor 3.x/Developers Guide

2010-01-19T15:03:37Z

TobiaszCudnik:

{{#CUSTOMTITLE:CKEditor 3.x - Developer's Guide}}

*[[CKEditor 3.x/Developers Guide/Installation|Installation]]
*[[CKEditor 3.x/Developers Guide/Integration|Integration]]
** [[CKEditor 3.x/Developers Guide/Integration/jQuery_Adapter|jQuery_Adapter]]
*Configuration
**[[CKEditor 3.x/Developers Guide/Setting Configurations|Setting Configurations]]
**[[CKEditor 3.x/Developers Guide/Toolbar|Toolbar]]
**[[CKEditor_3.x/Developers_Guide/Styles|Styles]]
**[[CKEditor 3.x/Developers Guide/Output Formatting|Output Formatting]]
**[[CKEditor 3.x/Developers Guide/Templates|Templates]]
**Spell Checker
**[[CKEditor 3.x/Developers Guide/File Browser (Uploader)|File Browser/Uploader ]]
*Customization
**Plugins
**Skins
*Advanced Tasks
**[[CKEditor_3.x/Developers_Guide/Editor_Core_URLs_Manipulation|Editor Core URLs Manipulation]]
*Deployment
*[http://docs.cksource.com/ckeditor_api/ JavaScript API]
*[[FCKeditor 3.x/Design and Architecture|Design and Architecture]]

CKEditor 3.x/jQuery Adapter

2010-01-19T15:01:05Z

TobiaszCudnik: moved CKEditor 3.x/jQuery Adapter to CKEditor 3.x/Developers Guide/Integration/jQuery Adapter: Fixed category.

#REDIRECT [[CKEditor 3.x/Developers Guide/Integration/jQuery Adapter]]

CKEditor 3.x/Developers Guide/jQuery Adapter

2010-01-19T15:01:05Z

TobiaszCudnik: moved CKEditor 3.x/jQuery Adapter to CKEditor 3.x/Developers Guide/Integration/jQuery Adapter: Fixed category.

The CKEditor jQuery Adapter provides deep integration into the jQuery JavaScript Library of the CKEditor, using native library's features

== Creating editor instances ==
To create editor instances, other than the usual CKEditor core script, you need to load the jQuery Adapter file in the page, in the following order:

<source language="html"><script type="text/javascript" src="/ckeditor/ckeditor.js"></script>
<script type="text/javascript" src="/ckeditor/adapters/jquery.js"></script></source>

At this point, any textarea, p or div element can be transformed into a rich text editor by simply using the ckeditor() method:
<source language="js">$( 'textarea.editor' ).ckeditor();</source>
jQuery chaining can also be used:
<source language="js">$( '.section-x' )
.find( 'textarea.editor' )
.ckeditor()
.end()
.find( 'a' )
.addClass( 'mylink' )
.end();</source>

The ckeditor() is the main method in the jQuery adapter. It accepts two optional parameters:
* A '''callback function''' to be execute when the editor is ready.
* '''Configuration options''' specific to the created editor instance.

The [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html configurations options] are passed through a simple object containing properties, each one related to a specific editor setting.</p>
<source language="js">$('.jquery_ckeditor')
.ckeditor( function() { /* callback code */ }, { skin : 'office2003' } );
.ckeditor( callback2 );</source>

Code above won't create 2 editors - it will discover that one is already during creation and wait with the second callback. Each of those callbacks will be executed in context of the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object (so "this" will be the editor) and the DOM element object will be passed as parameter.

== Code interaction with editor instances==
As soon as an editor instance is ready (after the above callback call), the ckeditorGet() method can then be used to retrieve a [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object that represents an editor instance. For example:
<source language="js">var editor = $('.jquery_ckeditor').ckeditorGet();
alert( editor.checkDirty() );
</source>

Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the dedicated val() method:
<source language="js">// Get the editor data.
var data = $( 'textarea.editor' ).val();
// Set the editor data.
$( 'textarea.editor' ).val( 'my new content' );</source>

This feature can be disabled by setting CKEDITOR.config.jqueryOverrideVal to false, before loading the adapter code.

For textareas, the editor will automatically return it's content back to the form when it is submitted. CKEditor also works with the official [http://jquery.malsup.com/form/ jQuery Form Plugin] for AJAX based forms. It doesn't require anything from the developer side.

== Events handling ==
Although CKEditor uses its own event system, there are four main events which we're exposing to the jQuery event system. All events use the event namespace, which is simply named ".ckeditor".

The following events are available:
* <strong>instanceReady.ckeditor</strong>: fired when the editor is created, but before any callback being passed to the ckeditor() method.
* <strong>setData.ckeditor</strong>: fired when data is set into the editor.
* <strong>getData.ckeditor</strong>: fired when data is fetched from the editor. The current editor data is also passed in the arguments.
* <strong>destroy.ckeditor</strong>: fired when the editor gets destroyed. It can be used, for example, to execute some cleanup on the page.

The editor instance is always passed as the first data argument for the listener. Both getData and setData are often used internally so listening to them should be done with care.

jQuery events DO bubble up through the DOM, so they can be listened selectively on certain parts of the document.

CKEditor 3.x/Developers Guide/jQuery Adapter

2010-01-19T14:59:13Z

TobiaszCudnik: jQuery adapter for CKEditor.

CKEditor 3.x/Developers Guide/Setting Configurations

2010-01-19T14:19:27Z

TobiaszCudnik:

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.

== Available Configuration Options ==

All available configuration options can be found inside our API documentation, inside the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html 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 [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">CKEDITOR.replace( 'editor1',
{
toolbar : 'Basic',
uiColor : '#9AB8F3'
});
</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.

== 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:
<source lang="javascript">CKEDITOR.editorConfig = function( config )
{
config.language = 'fr';
config.uiColor = '#AADC6E';
};
</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.

== 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 [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig customConfig] setting when creating the editor instances. For example:
<source lang="javascript">CKEDITOR.replace( 'editor1',
{
customConfig : '/custom/ckeditor_config.js'
});
</source>
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:

#The editor instance is created. At this point all its default configurations are set.
#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.
#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.
#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 [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig customConfig] setting to an empty string. For example:
<source lang="javascript">CKEDITOR.replace( 'editor1',
{
customConfig : ''
});
</source>
This setting is definitely recommended if you are not setting configurations in the config.js file nor a custom configuration file.

CKEditor 3.x/Developers Guide/Setting Configurations

2010-01-19T13:22:01Z

TobiaszCudnik:

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.

== Available Configuration Options ==

All available configuration options can be found inside our API documentation, inside the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html 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 [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">CKEDITOR.replace( 'editor1',
{
toolbar : 'Basic',
uiColor : '#9AB8F3'
});
</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.

== 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:
<source lang="javascript">CKEDITOR.editorConfig = function( config )
{
config.language = 'fr';
config.uiColor = '#AADC6E';
};
</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.

== 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 [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig customConfig] setting when creating the editor instances. For example:
<source lang="javascript">CKEDITOR.replace( 'editor1',
{
customConfig : '/custom/ckeditor_config.js'
});
</source>
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:

#The editor instance is created. At this point all its default configurations are set.
#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.
#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.
#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 [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.customConfig customConfig] setting to an empty string. For example:
<source lang="javascript">CKEDITOR.replace( 'editor1',
{
customConfig : ''
});
</source>
This setting is definitely recommended if you are not setting configurations in the config.js file nor a custom configuration file.