2009/09/04

Creating CKEditor instances with Javascript

This should be the final article about creating instances of CKEditor. The first one talked about the simple conversion of textareas and the second one about the new delayed loading feature.

This post will focus on how to create the editor in a more dynamical way (let's call that AJAX).

Replace or Append

One aspect that I didn't mention in the introduction to it, is that the replace function isn't restricted to textareas, as you can see in the examples, you can pass to it a DOM element, or an Id to be used with document.getElementById or a Name that matches a textarea in the page. So the first two options (DOM and Id) allow to use the editor with any kind of element (usually a div), not just textareas. A basic example is the divReplace.html sample (keep in mind that this is just a proof of concept, you will need to code quite a lot more in order to create a CMS with these features). The element being replaced isn't removed from the DOM, it just hidden with style="display:none; visibility:hidden" and the instance is populated with the innerHTML of that element.

Due to the usage of innerHTML and the way that it behaves in different browsers (specially IE) you might find that this isn't too useful, specially if you include any script in the source or any code that is processed at the server.

The appendTo function is the second option to dynamically create instances, and it also accepts as the first parameter a DOM element or an Id, but as the new editor will be created inside that element, it doesn't accept a name, and of course the element that you want to use as the parent must be a valid one (using it on a textarea is wrong and it won't work). An example to use this function is the ajax.html file.

Usually you will use appendTo with a newly created container, so it's empty, but just in case of doubt: appendTo obviously appends the CKEditor element as the last child of the container.

Notes about the creation

Whatever reference element that it's being used, it will be stored in editor.element (editor.element is a wrapper for the native DOM object that can be accessed in editor.element.$). If you are replacing a div or other non-form element, the Save button in the toolbar will be disabled. This should be obvious: its behavior is to update the reference element and then submit that form, if it can't submit the form then it can't save the data. You have two options in these situations: either remove the save button from your toolbar configuration, or create a mini-plugin that does take care to process the data in the way that you need.

The newly created instance will be named after the Id or Name of the replaced element, and if it doesn't have neither of those attributes or it isn't replacing an element, it will use an automatic counter. You can't use the .name property to rename an instance: the property will reflect the new value but it will remain with the old name in CKEDITOR.instances.

Both functions return the CKEditor object that has been created so you can keep working on it, but if you are using the fckeditor_basic.js integration, it might not be full featured until the full core is loaded and then it's really created. You can find this code in the ajax.html example to learn how to deal with this situation:

if ( editor.setData )
    editor.setData( html );
else
    CKEDITOR.on( 'loaded', function()
        {
            editor.setData( html );
        });

End of chapter

So I think that this covers all the current options related to creation of the instances. Of course, you could use directly the ckeditor constructor, but unless you are absolutely sure that you know what you are doing, you should avoid it.

In future releases you will have the option to use different plugins to some popular Javascript frameworks (the one in the works is for jQuery) so you can use CKEditor in a "native" way in that framework.

No comments: