Revision as of 13:09, 8 February 2011

The stylescombo plugin adds the Styles drop-down list to 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. In order to get a customized style list, you must prepare your style definition which is a simple JavaScript array containing the rules to be applied for each style.

The Styles Definition

The styles definition is a JavaScript array which is registered by calling the CKEDITOR.addStylesSet() function. A unique name must be assigned to your style definition, so you can later set each editor instance to load it. It means that you can have a single style definition which is shared by several editor instances present on the page.

The following is a sample style definition registration:

CKEDITOR.addStylesSet( 'my_styles',
[
    // Block 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 above definition registration can be placed inline in the page using the editor, or can even live in an external file, which is loaded "on demand", when needed only (see below).

After that, you must instruct the editor to use your newly registered style definition by using the stylesCombo_stylesSet setting. This may be set into the config.js file, for example:

config.stylesCombo_stylesSet = 'my_styles';

Using an External Styles Definition File

You can include the above styles definition registration call into an external JavaScript file. This is the preferred way for it because it will be loaded only when opening the Styles selection box, enhancing the page loading performance. Users may feel a small loading gap because of it though.

By default, the editor uses the "plugins/stylescombo/styles/default.js" file, which is a "minified" JavaScript file. You can find the uncompressed version of it at _source/plugins/stylescombo/styles/default.js. You can see it online at our SVN also: http://svn.fckeditor.net/CKEditor/trunk/_source/plugins/stylescombo/styles/default.js. It can be used as a template for your custom file.

Your style definition file can be saved anywhere at your web site (or the web). You must just know the URL to reach it. For example, you can save at it at the root of your web site, so you can reach it with /styles.js, or even place it in a central web site, so you can locate it with http://www.example.com/styles.js. At that point, simply change the stylesCombo_stylesSet setting to point the editor to your file:

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

OR

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

The above setting syntax is style definition name : file URL. Note that you must still use the unique name you have used to register the style definition into 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.