CKEditor for jQuery

Posted by tobiasz.cudnik

The new jQuery Adapter is our first integration effort for popular JavaScript libraries. We're proposing features tightly integrated with jQuery, while not introducing too many new methods to it. This article illustrates it, including some sample code snippets.

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:

<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 simply using the ckeditor() method:

$( 'textarea.editor' ).ckeditor();

jQuery chaining can also be used:

$( '.section-x' )
    .find( 'textarea.editor' )
        .ckeditor()
    .end()
    .find( 'a' )
        .addClass( 'mylink' )
    .end();

The ckeditor() is the main method in the jQuery adapter. It accepts two optional parameters:

  1. A callback function to be execute when the editor is ready;
  2. Configuration options specific to the created editor instance.

The configurations options are passed through a simple object containing properties, each one related to a specific editor setting.

$('.jquery_ckeditor')
    .ckeditor( function() { /* callback code */ }, { skin : 'office2003' } );

The "this" reference inside the callback function points to the the CKEDITOR.editor object representing the editor instance.

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 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 the dedicated val() method:

// 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 textareas, the editor will automatically return it's content back to the form when it is submitted. CKEditor also works with the official 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:

  • instanceReady.ckeditor: fired when the editor is created, but before any callback being passed to the ckeditor() method.
  • setData.ckeditor: fired when data is set into 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 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.

Feedback

Share your thoughts about our very first adapter. What's the best feature? What's missing? Which other adapters should we work on? Stay in touch!

  1. Westin Shafer's picture

    Westin Shafer

    Reply

    Hey everyone,

    I found that when using this adaptor it seems to break the built in save function of CkEditor.  The page submitted correctly, but the original values on the textareas was posted instead of what was typed in the editor.  

    I did however figure out a work around to get this working correctly.

    Basicly instead of initiating the editor using the above example I ended up using the following:

    $( 'textarea.editor').each( function() {

        CKEDITOR.replace( $(this).attr('id') );

    });

    Note: This assumes that each field that uses the editor is going to have it's own unique ID.

  2. Fawad's picture

    Fawad

    Reply

    Hi,

        I was trying to use ckeditor with official jQuery Form Plugin for AJAX based forms but with the first submit I dont get the data. If I submit it for the second time only then it works. Any suggestions on this?

    • Fawad's picture

      Fawad

      Reply

      Heye guys,

                         I found a solution for using ckeditor with JQuery ajaxForm plugin. Instead of doing the following

      $(document).ready(function() {
                  $('#myForm').ajaxForm(options);
              });

      do the following

        function submitAjaxForm(){
                  $('#myForm').ajaxForm(options);
              }

      and onsubmit of the form call this function.

      Hope it helps someone.

  3. Fawad's picture

    Fawad

    Reply

    Heye Guys,

                        I want to dynamically set the text to the ckeditor through javascript. Can anyone tell me how can I do that?