Revision as of 01:28, 3 September 2009

The "stylescombo" plugin adds a nice selection box to the toolbar, with which it's easy to apply customized styles and semantics value to the content.

The entries available in the style combo list can be easily customized to match your web site needs. For that, you must work on your styles definition, which is a simple JavaScript array containing the rules to be used 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

TODO: Explain the syntax used for the styles rules.