Revision as of 10:16, 13 January 2011

While CKEditor is full-featured WYSIWYG editor, not all of its options may be needed in all cases. Because of this, toolbar customization is one of the most common and required tasks when dealing with CKEditor.

Toolbar Definition

A toolbar definition is a JavaScript array that contains the elements to be displayed in all toolbar rows available in the editor.

The toolbar configuration can be defined in CKEditor using one of the following methods:

• The toolbar setting.
• The toolbar_name setting, where the name element is the name used to identify the toolbar in the toolbar setting.

The following code snippet contains the default CKEditor toolbar setting.

config.toolbar = 'Full';

config.toolbar_Full =
[
    ['Source','-','Save','NewPage','Preview','-','Templates'],
    ['Cut','Copy','Paste','PasteText','PasteFromWord','-','Print', 'SpellChecker', 'Scayt'],
    ['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'],
    ['Form', 'Checkbox', 'Radio', 'TextField', 'Textarea', 'Select', 'Button', 'ImageButton', 'HiddenField'],
    '/',
    ['Bold','Italic','Underline','Strike','-','Subscript','Superscript'],
    ['NumberedList','BulletedList','-','Outdent','Indent','Blockquote','CreateDiv'],
    ['JustifyLeft','JustifyCenter','JustifyRight','JustifyBlock'],
    ['BidiLtr', 'BidiRtl'],
    ['Link','Unlink','Anchor'],
    ['Image','Flash','Table','HorizontalRule','Smiley','SpecialChar','PageBreak','Iframe'],
    '/',
    ['Styles','Format','Font','FontSize'],
    ['TextColor','BGColor'],
    ['Maximize', 'ShowBlocks','-','About']
];

config.toolbar_Basic =
[
    ['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink','-','About']
];

Note that in the code above (just like in the default CKEditor configuration) two toolbar definitions have been defined. The first one is named Full and the second one is Basic. The toolbar was set to use the Full definition.

Toolbar Bands

Every toolbar definition is composed of a series of toolbar bands that are grouped in the final toolbar layout. The bands items move together to new rows when the editor is resized.

As visible in the code above, each toolbar band is defined as a separate JavaScript array of strings. Every string stands for a single toolbar item to be used. Toolbar items are defined by plugins.

You can also include a separator in the toolbar band by including a dash ("-") character in it.

Forcing Row Break

The Full definition contains numerous slash ("/") characters that were placed between toolbar bands. They can be used to force a break at the point where they were placed, rendering the next toolbar band in a new row. This placement will not be changed when CKEditor is resized.

Customizing the Toolbar

A simple way to configure all editors toolbar is by simply adding a custom toolbar definition inside the config.js file, or even better in a separated configuration file (see "Setting Configurations"). The easiest way for that is by simply copying the above "Full" toolbar definition, and strip it down to your needs. For example, the following is a good recommended toolbar definition to have in the config.js file:

CKEDITOR.editorConfig = function( config )
{
    config.toolbar = 'MyToolbar';

    config.toolbar_MyToolbar =
    [
        ['NewPage','Preview'],
        ['Cut','Copy','Paste','PasteText','PasteFromWord','-','Scayt'],
        ['Undo','Redo','-','Find','Replace','-','SelectAll','RemoveFormat'],
        ['Image','Flash','Table','HorizontalRule','Smiley','SpecialChar','PageBreak'],
        '/',
        ['Styles','Format'],
        ['Bold','Italic','Strike'],
        ['NumberedList','BulletedList','-','Outdent','Indent','Blockquote'],
        ['Link','Unlink','Anchor'],
        ['Maximize','-','About']
    ];
};

You can create as many toolbar definitions as you want inside the configuration file. Later, based on some criteria, you can decide the toolbar to use for each editor instance. For example, with the following code, two editors are created in the page, each one using a different toolbar:

CKEDITOR.replace( 'editor1',
    {
        toolbar : 'MyToolbar'
    });

CKEDITOR.replace( 'editor2',
    {
        toolbar : 'Basic'
    });

It's also possible to set the toolbar definition in-page, when creating the editor instance directly. In that case, just assign it to the toolbar setting directly, for example:

CKEDITOR.replace( 'editor1',
    {
        toolbar :
        [
            ['Styles', 'Format'],
            ['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', '-', 'About']
        ]
    });