Ext.data.JsonP.dev_toolbarconcepts({"guide":"<h1 id='dev_toolbarconcepts-section-understanding-ckeditor-toolbar-concepts'>Understanding CKEditor Toolbar Concepts</h1>\n<div class='toc'>\n<p><strong>Contents</strong></p>\n<ol>\n<li><a href='#!/guide/dev_toolbarconcepts-section-toolbar-groups-configuration'>Toolbar Groups Configuration</a><ol>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-changing-the-groups-order'>Changing the Groups Order</a></li>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-the-benefits-of-group-configuration'>The Benefits of Group Configuration</a></li>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-the-drawbacks-of-group-configuration'>The Drawbacks of Group Configuration</a></li>\n</ol>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-%22item-by-item%22-configuration'>\"Item by Item\" Configuration</a><ol>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-the-benefits-of-%22item-by-item%22-configuration'>The Benefits of \"Item by Item\" Configuration</a></li>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-the-drawbacks-of-%22item-by-item%22-configuration'>The Drawbacks of \"Item by Item\" Configuration</a></li>\n</ol>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-accessibility-concerns'>Accessibility Concerns</a></li>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-custom-toolbar-demo'>Custom Toolbar Demo</a></li>\n<li>\n<a href='#!/guide/dev_toolbarconcepts-section-related-features'>Related Features</a></li></ol>\n</div>\n\n<p>CKEditor 4 introduced a new concept for toolbar organization which is based on \"grouping\" instead of the traditional \"item by item positioning\" way. The aim of this article is to explain the concepts behind the editor toolbar and to help you choose the most optimal, accessibility-friendly and future-proof method to configure your toolbar.</p>\n\n<p class=\"tip\">\n    While this article explains how you can configure the editor toolbar manually, this approach is not recommended. It is much easier and quicker to <a href=\"#!/guide/dev_toolbar\">use the toolbar configurator</a>. The configurator was introduced in <strong>CKEditor 4.5</strong> and is available in each official CKEditor installation package. \n</p>\n\n\n<h2 id='dev_toolbarconcepts-section-toolbar-groups-configuration'>Toolbar Groups Configuration</h2>\n\n<p><strong>Note:</strong> This approach is used in the <a href=\"#!/guide/dev_toolbar-section-basic-toolbar-configurator\">basic mode of the toolbar configurator</a>, which is the most recommended method to customize the editor toolbar. If you do not want to use the toolbar configurator, this method requires manual crafting of the toolbar configuration code and is recommended to more advanced users only.</p>\n\n<p>Grouping configuration is defined by the <a href=\"#!/api/CKEDITOR.config-cfg-toolbarGroups\" rel=\"CKEDITOR.config-cfg-toolbarGroups\" class=\"docClass\">CKEDITOR.config.toolbarGroups</a> setting. The following is the configuration used by the Standard distribution of CKEditor:</p>\n\n<pre><code>config.toolbarGroups = [\n    { name: 'clipboard',   groups: [ 'clipboard', 'undo' ] },\n    { name: 'editing',     groups: [ 'find', 'selection', 'spellchecker' ] },\n    { name: 'links' },\n    { name: 'insert' },\n    { name: 'forms' },\n    { name: 'tools' },\n    { name: 'document',    groups: [ 'mode', 'document', 'doctools' ] },\n    { name: 'others' },\n    '/',\n    { name: 'basicstyles', groups: [ 'basicstyles', 'cleanup' ] },\n    { name: 'paragraph',   groups: [ 'list', 'indent', 'blocks', 'align', 'bidi' ] },\n    { name: 'styles' },\n    { name: 'colors' },\n    { name: 'about' }\n];\n</code></pre>\n\n<p>It is a list (<code>Array</code>) of objects, each one with a <code>name</code> (e.g <code>clipboard</code> or <code>links</code>) and an optional \"sub-groups\" list.</p>\n\n<h3 id='dev_toolbarconcepts-section-changing-the-groups-order'>Changing the Groups Order</h3>\n\n<p>You can easily customize the group ordering and position by simply changing the above configuration.</p>\n\n<p>You can force row breaks in the toolbar by adding <code>'/'</code> into the list, just like you can see in the code above.</p>\n\n<p>Note that there are unused groups in the above configuration. This is \"by design\" (see \"The Benefits of Group Configuration\" below).</p>\n\n<h3 id='dev_toolbarconcepts-section-the-benefits-of-group-configuration'>The Benefits of Group Configuration</h3>\n\n<p>The most important benefit of toolbar grouping configuration over the \"item by item\" configuration is: <strong>automation</strong>.</p>\n\n<p>It is now possible for plugin developers to define into which toolbar group their plugins should add buttons. For example, the <a href=\"http://ckeditor.com/addon/image\">Image</a> plugin includes its button in the <code>insert</code> group, while the <a href=\"http://ckeditor.com/addon/undo\">Undo and Redo</a> buttons go into the <code>undo</code> sub-group.</p>\n\n<p>While not mandatory, having all groups and sub-groups configured (including the ones that you do not use) is recommended because at any moment in the future, when a new plugin gets installed, its button will automatically appear in the toolbar without further configuration requirements.</p>\n\n<h3 id='dev_toolbarconcepts-section-the-drawbacks-of-group-configuration'>The Drawbacks of Group Configuration</h3>\n\n<p>The most evident problem with grouping configuration is that it is not possible to precisely control where each item is placed in the toolbar. A plugin author can influence it when <a href=\"#!/api/CKEDITOR.ui-method-addButton\">creating the toolbar button</a>, but it is entirely optional and cannot be easily configured by the developer customizing their CKEditor instance.</p>\n\n<h2 id='dev_toolbarconcepts-section-%22item-by-item%22-configuration'>\"Item by Item\" Configuration</h2>\n\n<p><strong>Note:</strong> This approach is used in the <a href=\"#!/guide/dev_toolbar-section-advanced-toolbar-configurator\">advanced mode of the toolbar configurator</a>, which is a much more recommended method to customize the editor toolbar. If you do not want to use the toolbar configurator, this method requires manual crafting of the toolbar configuration code and is recommended to more advanced users only.</p>\n\n<p>Other than the grouping configuration, it is also possible to have more control over every single element in the toolbar by defining their precise position. That is done by setting a \"toolbar definition\".</p>\n\n<p>A <a href=\"#!/api/CKEDITOR.config-cfg-toolbar\">toolbar definition</a> is a JavaScript array that contains the elements to\nbe displayed in all <strong>toolbar rows</strong> available in the editor. The following is an example:</p>\n\n<pre><code>config.toolbar = [\n    { name: 'document', items: [ 'Source', '-', 'NewPage', 'Preview', '-', 'Templates' ] },\n    { name: 'clipboard', items: [ 'Cut', 'Copy', 'Paste', 'PasteText', 'PasteFromWord', '-', 'Undo', 'Redo' ] },\n    '/',\n    { name: 'basicstyles', items: [ 'Bold', 'Italic' ] }\n];\n</code></pre>\n\n<p>Here every toolbar group is given a name and a precise list of items is defined for each group.</p>\n\n<p>The above can also be achieved with a simpler syntax (see \"Accessibility Concerns\" later on):</p>\n\n<pre><code>config.toolbar = [\n    [ 'Source', '-', 'NewPage', 'Preview', '-', 'Templates' ],\n    [ 'Cut', 'Copy', 'Paste', 'PasteText', 'PasteFromWord', '-', 'Undo', 'Redo' ],\n    '/',\n    [ 'Bold', 'Italic' ]\n];\n</code></pre>\n\n<p>Item separator can be included by adding <code>'-'</code> (dash) to the list of items, as seen above.</p>\n\n<p>You can force row breaks in the toolbar by adding <code>'/'</code> between groups. These separators can be used to force a\nbreak at the point where they were placed, rendering the next toolbar group in a new row.</p>\n\n<h3 id='dev_toolbarconcepts-section-the-benefits-of-%22item-by-item%22-configuration'>The Benefits of \"Item by Item\" Configuration</h3>\n\n<p>The most evident benefit of this kind of configuration is that the position of every single item in the toolbar is under control.</p>\n\n<h3 id='dev_toolbarconcepts-section-the-drawbacks-of-%22item-by-item%22-configuration'>The Drawbacks of \"Item by Item\" Configuration</h3>\n\n<p>The biggest problem it that there will be no automation when new plugins get installed. This means that if a new plugin gets into your editor, you will have to manually change your configuration to include the plugin buttons.</p>\n\n<h2 id='dev_toolbarconcepts-section-accessibility-concerns'>Accessibility Concerns</h2>\n\n<p>The <code>name</code> given for every toolbar group is used by assistive technologies such as screen\nreaders. That name will be used by CKEditor to search for the \"readable\" name of each toolbar group in the editor language files (the <code>toolbarGroups</code> entries).</p>\n\n<p>Screen readers will announce each of the toolbar groups by using either their readable name (if it is available) or their defined <code>name</code> attribute.</p>\n\n<h2 id='dev_toolbarconcepts-section-custom-toolbar-demo'>Custom Toolbar Demo</h2>\n\n<p>See the <a href=\"../samples/toolbar.html\">working \"Custom Editor Toolbar\" sample</a> that showcases an editor instance with a one-row toolbar set to include just a few most relevant editing features.</p>\n\n<h2 id='dev_toolbarconcepts-section-related-features'>Related Features</h2>\n\n<p>Refer to the following resources for more information about editor toolbar:</p>\n\n<ul>\n<li>The <a href=\"#!/guide/dev_toolbar\">Toolbar Configuration</a> article explains how to set up the editor toolbar using the toolbar configurator (CKEditor 4.5+).</li>\n<li>The <a href=\"#!/guide/dev_toolbarlocation\">Toolbar Location</a> feature lets you change the toolbar position in classic editor.</li>\n<li>The <a href=\"#!/guide/dev_sharedspace\">Shared Toolbar and Bottom Bar</a> feature lets you place the toolbar in a designated page element and share it among multiple editor instances used on one page.</li>\n</ul>\n\n","title":"Toolbar Concepts","meta_description":"Understanding CKEditor toolbar concepts.","meta_keywords":"ckeditor, editor, wysiwyg, ui, interface, toolbar, buttons, groups, items, accessibility, configure, configuration, setup, settings, options, customization, customize, customise, customisation, config, modification, modify, change"});