Revision as of 19:28, 8 March 2011

The stylescombo plugin adds the Styles drop-down list to the CKEditor toolbar. The list makes it easy to apply customized styles and semantic values to content created in the editor.

The entries available in the Styles drop-down list can be easily customized to suit your needs. If you want to have a customized style list, you will need to prepare the style definitions in a form of JavaScript arrays containing the rules to be applied for each style.

Defining Styles

The styles definition is a JavaScript array which is registered by calling the CKEDITOR.stylesSet.add function. A unique name must be assigned to your style definition, so you can later configure each editor instance to load it. This method lets you have a single style definition which is shared by several CKEditor instances present on the page.

The following code shows how to register a sample style definition.

CKEDITOR.stylesSet.add( 'my_styles',
[
    // Block-level styles
    { name : 'Blue Title', element : 'h2', styles : { 'color' : 'Blue' } },
    { name : 'Red Title' , element : 'h3', styles : { 'color' : 'Red' } },

    // Inline styles
    { name : 'CSS Style', element : 'span', attributes : { 'class' : 'my_style' } },
    { name : 'Marker: Yellow', element : 'span', styles : { 'background-color' : 'Yellow' } }
]);

The definition registration like the one above can be placed inline in the page source, or can live in an external file which is loaded "on demand", when needed only (see below).

When the definitions are ready, you must instruct the editor to apply the newly registered styles by using the stylesSet setting. This may be set in the config.js file, for example:

config.stylesSet = 'my_styles';

Using an External Styles Definition File

The style definition registration call can be included in an external JavaScript file. This method is recommended, because it allows you to load the definitions only on opening the Styles drop-down list, thus decreasing the editor page loading time. This approach means, however, that the users opening the Styles list may feel a minor loading delay.

By default, CKEditor uses the plugins/styles/styles/default.js file, which is a minified JavaScript file.

The uncompressed version of this file can be found in the CKEditor package as _source/plugins/styles/styles/default.js. You can also see it online in our SVN repository: http://svn.ckeditor.com/CKEditor/trunk/_source/plugins/styles/styles/default.js. This file can be used as a template for your custom file.

Your style definition file can be saved in any place of your website (or somewhere in the Internet). You must, however, know the URL required to reach it. For example, you can save the file at the root of your website, and then call it as /styles.js, or place it anywhere else, and refer to it using its full URL, like http://www.example.com/styles.js.

At that point, change the stylesSet setting to point the editor to your file:

config.stylesSet = 'my_styles:/styles.js';

OR

config.stylesSet = 'my_styles:http://www.example.com/styles.js';

The syntax for the style definition setting is always: style definition name : file URL.

Note that you must use the unique name you have used to register the style definition in the file.

Style Rules

The entries inside a style definition are called "style rules". Each rule defines the display name for a single style as well as the element, attributes, and CSS styles to be used for it. The following is the generic representation for it:

{
    name : 'Display name',
    element : 'tag name (for example "span")',
    styles :
    {
        'css-style1' : 'desired value',
        'css-style2' : 'desired value',
        ...
    }
    attributes :
    {
        'attribute-name1' : 'desired value',
        'attribute-name2' : 'desired value',
        ...
    }
}

The name and element values are required, while other values are optional.

Style Types

There are three types of style types, each one related to the element used in the style rule:

• Block styles – applied to the text blocks (paragraphs) as a whole, not limited to the text selection. The elements values for that are: address, div, h1, h2, h3, h4, h5, h6, p, and pre.
• Object styles – applied to special selectable objects (not textual), whenever such selection is supported by the browser. The elements values for that are: a, embed, hr, img, li, object, ol, table, td, tr and ul.
• Inline styles – applied to text selections for style rules using elements not defined in the other style types.