CKEditor 3.x/Developers Guide/jQuery Adapter - Revision history

Anna: /* Code Interaction with Editor Instances */ val() function clarification added

2011-03-10T14:14:36Z

‎Code Interaction with Editor Instances: val() function clarification added

Anna: /* Creating Editor Instances */ Redundant semi-colon removed

2011-03-10T14:00:37Z

‎Creating Editor Instances: Redundant semi-colon removed

Anna: /* Code Interaction with Editor Instances */ Link to API added

2011-02-22T14:18:31Z

‎Code Interaction with Editor Instances: Link to API added

Anna: /* Events handling */ Section proof-read and formatted

2011-01-13T07:01:46Z

‎Events handling: Section proof-read and formatted

Anna: /* Code Interaction with Editor Instances */ Section proof-read

2011-01-13T06:57:22Z

‎Code Interaction with Editor Instances: Section proof-read

Anna: /* Creating Editor Instances */ Minor rewording

2011-01-13T06:47:21Z

‎Creating Editor Instances: Minor rewording

Anna: /* Code interaction with editor instances */ Minor proof-reading changes

2011-01-11T13:53:52Z

‎Code interaction with editor instances: Minor proof-reading changes

Anna: /* Creating editor instances */ Section proof-read

2011-01-11T12:43:44Z

‎Creating editor instances: Section proof-read

TobiaszCudnik at 09:04, 20 January 2010

2010-01-20T09:04:30Z

Fredck at 17:42, 19 January 2010

2010-01-19T17:42:09Z

@@ Line 42: / Line 42: @@
 </source>
-Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides a dedicated <code>val()</code> method:
+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.
@@ Line 52: / Line 52: @@
 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 <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.
+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 ==

@@ Line 29: / Line 29: @@
 <source language="js">
 $('.jquery_ckeditor')
-     .ckeditor( function() { /* callback code */ }, { skin : 'office2003' } );
+     .ckeditor( function() { /* callback code */ }, { skin : 'office2003' } )
      .ckeditor( callback2 );
 </source>

@@ Line 50: / Line 50: @@
 </source>
-This feature can be disabled by setting <code>CKEDITOR.config.jqueryOverrideVal</code> to false before loading the adapter code.
+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 <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.

@@ Line 54: / Line 54: @@
 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.
-== Events handling ==
+== Event 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 &quot;.ckeditor&quot;.
+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:
-* <strong>instanceReady.ckeditor</strong>: fired when the editor is created, but before any callback being passed to the ckeditor() method.
+* <code><strong>instanceReady.ckeditor</strong></code> &ndash; fired when the editor is created, but before any callback is being passed to the <code>ckeditor()</code> method.
-* <strong>setData.ckeditor</strong>: fired when data is set into the editor.
+* <code><strong>setData.ckeditor</strong></code> &ndash; fired when data is set in the editor.
-* <strong>getData.ckeditor</strong>: fired when data is fetched from the editor. The current editor data is also passed in the arguments.
+* <code><strong>getData.ckeditor</strong></code> &ndash; 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.
+* <code><strong>destroy.ckeditor</strong></code> &ndash; 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 DO bubble up through the DOM, so they can be listened selectively on certain parts of the document.
+jQuery events ''do'' bubble up through the DOM, so they can be listened to selectively in certain parts of the document.

@@ Line 36: / Line 36: @@
 == Code Interaction with Editor Instances ==
-As soon as an editor instance is ready (after the callback call demonstrated above), the <code>ckeditorGet()</code> method can then be used to retrieve a <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.editor.html CKEDITOR.editor]</code> object that represents an editor instance. For example:
+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();
@@ Line 42: / Line 42: @@
 </source>
-Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the dedicated <code>val()</code> method:
+Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides a dedicated <code>val()</code> method:
 <source language="js">
 // Get the editor data.
@@ Line 50: / Line 50: @@
 </source>
-This feature can be disabled by setting <code>CKEDITOR.config.jqueryOverrideVal</code> to false, before loading the adapter code.
+This feature can be disabled by setting <code>CKEDITOR.config.jqueryOverrideVal</code> to false before loading the adapter code.
-For <code>textarea</code> elements, the editor will automatically return its 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 does not require anything from the developer's side.
+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.
 == Events handling ==

@@ Line 26: / Line 26: @@
 * '''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 that contain properties, each one related to a specific editor setting.
+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')

@@ Line 35: / Line 35: @@
 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 interaction with editor instances==
+== 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:
+As soon as an editor instance is ready (after the callback call demonstrated above), the <code>ckeditorGet()</code> method can then be used to retrieve a <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">
 alert( editor.checkDirty() );
 </source>
-Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the dedicated val() method:
+Because setting and retrieving the editor data is a common operation, the jQuery Adapter also provides the dedicated <code>val()</code> method:
-<source language="js">// Get the editor data.
+<source language="js">
 var data = $( 'textarea.editor' ).val();
 // Set the editor data.
-$( 'textarea.editor' ).val( 'my new content' );</source>
+$( 'textarea.editor' ).val( 'my new content' );
-This feature can be disabled by setting CKEDITOR.config.jqueryOverrideVal to false, before loading the adapter code.
+This feature can be disabled by setting <code>CKEDITOR.config.jqueryOverrideVal</code> 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.
+For <code>textarea</code> elements, the editor will automatically return its 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 does not require anything from the developer's side.
 == Events handling ==

@@ 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.
-== Creating editor instances ==
+== 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:
+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>
-At this point, any textarea, p or div element can be transformed into a rich text editor by simply using the ckeditor() method:
+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>
-jQuery chaining can also be used:
 <source language="js">$( '.section-x' )
      .find( 'textarea.editor' )
@@ Line 19: / Line 22: @@
      .end();</source>
-The ckeditor() is the main method in the jQuery adapter. It accepts two optional parameters:
+The <code>ckeditor()</code> method is the main method of the jQuery adapter. It accepts two optional parameters:
-* A '''callback function''' to be execute when the editor is ready.
+* A '''callback function''' to be executed 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>
+The [http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html configurations options] are passed through a simple object that contain properties, each one related to a specific editor setting.
-<source language="js">$('.jquery_ckeditor')
+<source language="js">
      .ckeditor( function() { /* callback code */ }, { skin : 'office2003' } );
-     .ckeditor( callback2 );</source>
+     .ckeditor( callback2 );
-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.
+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 interaction with editor instances==