m |
(→Code Interaction with Editor Instances: val() function clarification added) |
||
(7 intermediate revisions by the same user not shown) | |||
Line 1: | Line 1: | ||
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. | 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 | + | == Creating Editor Instances == |
− | + | In order to create editor instances, load the usual CKEditor core script file as well as the jQuery Adapter file, in the following order: | |
− | <source language="html"><script type="text/javascript" src="/ckeditor/ckeditor.js"></script> | + | <source language="html"> |
− | <script type="text/javascript" src="/ckeditor/adapters/jquery.js"></script></source> | + | <script type="text/javascript" src="/ckeditor/ckeditor.js"></script> |
+ | <script type="text/javascript" src="/ckeditor/adapters/jquery.js"></script> | ||
+ | </source> | ||
− | At this point | + | At this point any <code>textarea</code>, <code>p</code>, or <code>div</code> element can be transformed into a rich text editor by using the <code>ckeditor()</code> method. |
<source language="js">$( 'textarea.editor' ).ckeditor();</source> | <source language="js">$( 'textarea.editor' ).ckeditor();</source> | ||
− | jQuery chaining | + | |
+ | Note that you can also make use of the jQuery chaining. | ||
<source language="js">$( '.section-x' ) | <source language="js">$( '.section-x' ) | ||
.find( 'textarea.editor' ) | .find( 'textarea.editor' ) | ||
Line 19: | Line 22: | ||
.end();</source> | .end();</source> | ||
− | The ckeditor() is the main method | + | The <code>ckeditor()</code> method is the main method of the jQuery adapter. It accepts two optional parameters: |
− | * A '''callback function''' to be | + | * A '''callback function''' to be executed when the editor is ready. |
* '''Configuration options''' specific to the created editor instance. | * '''Configuration options''' specific to the created editor instance. | ||
− | The [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html | + | The [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html configuration options] are passed through a simple object that contains properties, each one related to a specific editor setting. |
− | <source language="js">$('.jquery_ckeditor') | + | <source language="js"> |
− | .ckeditor( function() { /* callback code */ }, { skin : 'office2003' } ) | + | $('.jquery_ckeditor') |
− | .ckeditor( callback2 );</source> | + | .ckeditor( function() { /* callback code */ }, { skin : 'office2003' } ) |
+ | .ckeditor( callback2 ); | ||
+ | </source> | ||
− | + | The code presented above will not create two editors. On discovering that one editor is already being created, it will wait with the second callback. Each of the callback functions will be executed in the context of the [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor] object (so <code>this</code> will be the editor) and the DOM element object will be passed as parameter. | |
− | == Code | + | == Code Interaction with Editor Instances == |
− | + | When an editor instance is ready (after the callback call demonstrated above), the <code>ckeditorGet()</code> method can be used to retrieve the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor]</code> object that represents an editor instance. For example: | |
− | <source language="js">var editor = $('.jquery_ckeditor').ckeditorGet(); | + | <source language="js"> |
+ | var editor = $('.jquery_ckeditor').ckeditorGet(); | ||
alert( editor.checkDirty() ); | alert( editor.checkDirty() ); | ||
</source> | </source> | ||
− | Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the | + | Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides a dedicated <code>val()</code> method that is an extension of the original jQuery <code>val()</code> method. This method works exactly the same as the jQuery version, but additionally it allows to get and set the editor contents. |
− | <source language="js">// Get the editor data. | + | <source language="js"> |
+ | // Get the editor data. | ||
var data = $( 'textarea.editor' ).val(); | var data = $( 'textarea.editor' ).val(); | ||
// Set the editor data. | // Set the editor data. | ||
− | $( 'textarea.editor' ).val( 'my new content' );</source> | + | $( 'textarea.editor' ).val( 'my new content' ); |
+ | </source> | ||
− | This feature can be disabled by setting CKEDITOR.config.jqueryOverrideVal to false | + | This feature can be disabled by setting <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.jqueryOverrideVal CKEDITOR.config.jqueryOverrideVal]</code> to false before loading the adapter code. |
− | For | + | For <code><textarea></code> elements the editor will automatically return its content back to the form when it is submitted. CKEditor also automatically works with the official [http://jquery.malsup.com/form/ jQuery Form Plugin] for AJAX based forms. It does not require any action from the developer's side to support it. |
− | == | + | == Event handling == |
− | Although CKEditor uses its own event system, there are four main events which | + | Although CKEditor uses its own event system, there are four main events which are being exposed to the jQuery event system. All events use the event namespace, which is simply named <code>.ckeditor</code>. |
The following events are available: | The following events are available: | ||
− | * <strong>instanceReady.ckeditor</strong> | + | * <code><strong>instanceReady.ckeditor</strong></code> – fired when the editor is created, but before any callback is being passed to the <code>ckeditor()</code> method. |
− | * <strong>setData.ckeditor</strong> | + | * <code><strong>setData.ckeditor</strong></code> – fired when data is set in the editor. |
− | * <strong>getData.ckeditor</strong> | + | * <code><strong>getData.ckeditor</strong></code> – fired when data is fetched from the editor. The current editor data is also passed in the arguments. |
− | * <strong>destroy.ckeditor</strong> | + | * <code><strong>destroy.ckeditor</strong></code> – fired when the editor gets destroyed. It can be used, for example, to execute some cleanup code 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. | + | The editor instance is always passed as the first data argument for the listener. Both <code>getData</code> and <code>setData</code> are often used internally, so listening to them should be done with care. |
− | jQuery events | + | jQuery events ''do'' bubble up through the DOM, so they can be listened to selectively in certain parts of the document. |
Latest revision as of 15:14, 10 March 2011
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
In order to create editor instances, load the usual CKEditor core script file as well as the jQuery Adapter file, in the following order:
<script type="text/javascript" src="/ckeditor/ckeditor.js"></script> <script type="text/javascript" src="/ckeditor/adapters/jquery.js"></script>
At this point any textarea
, p
, or div
element can be transformed into a rich text editor by using the ckeditor()
method.
$( 'textarea.editor' ).ckeditor();
Note that you can also make use of the jQuery chaining.
$( '.section-x' ) .find( 'textarea.editor' ) .ckeditor() .end() .find( 'a' ) .addClass( 'mylink' ) .end();
The ckeditor()
method is the main method of the jQuery adapter. It accepts two optional parameters:
- A callback function to be executed when the editor is ready.
- Configuration options specific to the created editor instance.
The configuration options are passed through a simple object that contains properties, each one related to a specific editor setting.
$('.jquery_ckeditor') .ckeditor( function() { /* callback code */ }, { skin : 'office2003' } ) .ckeditor( callback2 );
The code presented above will not create two editors. On discovering that one editor is already being created, it will wait with the second callback. Each of the callback functions will be executed in the context of the CKEDITOR.editor object (so this
will be the editor) and the DOM element object will be passed as parameter.
Code Interaction with Editor Instances
When an editor instance is ready (after the callback call demonstrated above), the ckeditorGet()
method can be used to retrieve the CKEDITOR.editor
object that represents an editor instance. For example:
var editor = $('.jquery_ckeditor').ckeditorGet(); alert( editor.checkDirty() );
Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides a dedicated val()
method that is an extension of the original jQuery val()
method. This method works exactly the same as the jQuery version, but additionally it allows to get and set the editor contents.
// Get the editor data. var data = $( 'textarea.editor' ).val(); // Set the editor data. $( 'textarea.editor' ).val( 'my new content' );
This feature can be disabled by setting CKEDITOR.config.jqueryOverrideVal
to false before loading the adapter code.
For <textarea>
elements the editor will automatically return its content back to the form when it is submitted. CKEditor also automatically works with the official jQuery Form Plugin for AJAX based forms. It does not require any action from the developer's side to support it.
Event handling
Although CKEditor uses its own event system, there are four main events which are being exposed to the jQuery event system. All events use the event namespace, which is simply named .ckeditor
.
The following events are available:
-
instanceReady.ckeditor
– fired when the editor is created, but before any callback is being passed to theckeditor()
method. -
setData.ckeditor
– fired when data is set in the editor. -
getData.ckeditor
– fired when data is fetched from the editor. The current editor data is also passed in the arguments. -
destroy.ckeditor
– fired when the editor gets destroyed. It can be used, for example, to execute some cleanup code 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 to selectively in certain parts of the document.