CKEditor Toolbar

This website contains links to software which is either no longer maintained or will be supported only until the end of 2019 (CKFinder 2). For the latest documentation about current CKSource projects, including software like CKEditor 4/CKEditor 5, CKFinder 3, Cloud Services, Letters, Accessibility Checker, please visit the new documentation website.

If you look for an information about very old versions of CKEditor, FCKeditor and CKFinder check also the CKEditor forum, which was closed in 2015. If not, please head to StackOverflow for support.

(Introduction text proof-read, code formatted)
Line 1: Line 1:
While the editor is full featured, not all options may be needed in all cases. Because of this, customizing the toolbar is one of the most common and required tasks when dealing with CKEditor.  
+
{{#CUSTOMTITLE:CKEditor Toolbar}}
 
+
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  ==
 
  
 +
== Toolbar Definition  ==
 
A toolbar definition is a JavaScript array that contains the elements to be displayed in all "toolbar rows" available in the editor. There are two ways to set the desired toolbar definition in the editor. It can be set directly into the "toolbar" setting, or it can instead be set to a configuration named "toolbar_<name>", where "<name>" is a name that can be used to identify the toolbar in the "[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.toolbar toolbar]" setting. The following is the default setting we have in the editor.  
 
A toolbar definition is a JavaScript array that contains the elements to be displayed in all "toolbar rows" available in the editor. There are two ways to set the desired toolbar definition in the editor. It can be set directly into the "toolbar" setting, or it can instead be set to a configuration named "toolbar_<name>", where "<name>" is a name that can be used to identify the toolbar in the "[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.toolbar toolbar]" setting. The following is the default setting we have in the editor.  
<pre>config.toolbar = 'Full';
+
<source language="js">
 +
config.toolbar = 'Full';
  
 
config.toolbar_Full =
 
config.toolbar_Full =
Line 29: Line 30:
 
     ['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink','-','About']
 
     ['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', 'Unlink','-','About']
 
];
 
];
</pre>  
+
</source>  
 
Note that two toolbar definitions have been defined, one named "Full" and the other "Basic". The "Full" definition has been set to be used in the toolbar setting.  
 
Note that two toolbar definitions have been defined, one named "Full" and the other "Basic". The "Full" definition has been set to be used in the toolbar setting.  
  
 
=== Toolbar Bands  ===
 
=== 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 on new rows when resizing the editor.  
 
Every toolbar definition is composed of a series of "toolbar bands" that are grouped in the final toolbar layout. The bands items move together on new rows when resizing the editor.  
  
Line 41: Line 41:
  
 
=== Forcing Row Break  ===
 
=== Forcing Row Break  ===
 
 
Looking at the "Full" definition you will note some slash ("/") characters between toolbar bands. This slash can be used to force a break at that point, having the next band to be rendered in a new row and not following the previous one.
 
Looking at the "Full" definition you will note some slash ("/") characters between toolbar bands. This slash can be used to force a break at that point, having the next band to be rendered in a new row and not following the previous one.
  
== Customizing the toolbar ==
+
== 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 "[[CKEditor_3.x/Developers_Guide/Setting_Configurations|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:  
 
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 "[[CKEditor_3.x/Developers_Guide/Setting_Configurations|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:  
<pre>CKEDITOR.editorConfig = function( config )
+
<source language="js">
 +
CKEDITOR.editorConfig = function( config )
 
{
 
{
 
     config.toolbar = 'MyToolbar';
 
     config.toolbar = 'MyToolbar';
Line 65: Line 64:
 
     ];
 
     ];
 
};
 
};
</pre>  
+
</source>  
 
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:  
 
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:  
<pre>CKEDITOR.replace( 'editor1',
+
<source language="js">
 +
CKEDITOR.replace( 'editor1',
 
     {
 
     {
 
         toolbar&nbsp;: 'MyToolbar'
 
         toolbar&nbsp;: 'MyToolbar'
Line 76: Line 76:
 
         toolbar&nbsp;: 'Basic'
 
         toolbar&nbsp;: 'Basic'
 
     });
 
     });
</pre>  
+
</source>  
 
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:  
 
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:  
<pre>CKEDITOR.replace( 'editor1',
+
<source language="js">
 +
CKEDITOR.replace( 'editor1',
 
     {
 
     {
 
         toolbar&nbsp;:
 
         toolbar&nbsp;:
Line 86: Line 87:
 
         ]
 
         ]
 
     });
 
     });
</pre>
+
</source>

Revision as of 09:51, 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. There are two ways to set the desired toolbar definition in the editor. It can be set directly into the "toolbar" setting, or it can instead be set to a configuration named "toolbar_<name>", where "<name>" is a name that can be used to identify the toolbar in the "toolbar" setting. The following is the default setting we have in the editor.

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'],
    ['BidiLtr', 'BidiRtl'],
    '/',
    ['Bold','Italic','Underline','Strike','-','Subscript','Superscript'],
    ['NumberedList','BulletedList','-','Outdent','Indent','Blockquote','CreateDiv'],
    ['JustifyLeft','JustifyCenter','JustifyRight','JustifyBlock'],
    ['Link','Unlink','Anchor'],
    ['Image','Flash','Table','HorizontalRule','Smiley','SpecialChar','PageBreak'],
    '/',
    ['Styles','Format','Font','FontSize'],
    ['TextColor','BGColor'],
    ['Maximize', 'ShowBlocks','-','About']
];

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

Note that two toolbar definitions have been defined, one named "Full" and the other "Basic". The "Full" definition has been set to be used in the toolbar setting.

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 on new rows when resizing the editor.

As you can see in the above definitions, every toolbar band is defined as a separated JavaScript array of strings. Every string indicates toolbar item to be used. Toolbar items are defined by plugins.

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

Forcing Row Break

Looking at the "Full" definition you will note some slash ("/") characters between toolbar bands. This slash can be used to force a break at that point, having the next band to be rendered in a new row and not following the previous one.

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&nbsp;: 'MyToolbar'
    });

CKEDITOR.replace( 'editor2',
    {
        toolbar&nbsp;: '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&nbsp;:
        [
            ['Styles', 'Format'],
            ['Bold', 'Italic', '-', 'NumberedList', 'BulletedList', '-', 'Link', '-', 'About']
        ]
    });