Styles"

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.

(Style Rules: Missing apostrophes added)
(Stylesheet Parser Plugin: Some clarification about styles added)
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
__TOC__
 
__TOC__
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 <code>stylescombo</code> plugin adds the [[CKEditor 3.x/Users Guide/Styling/Styles|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 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 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.
  
== The Styles Definition ==
+
== Defining Styles ==
The styles definition is a JavaScript array which is registered by calling the <code>CKEDITOR.addStylesSet()</code> 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 styles definition is a JavaScript array which is registered by calling the <code>CKEDITOR.stylesSet.add</code> 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 is a sample style definition registration:
+
The following code shows how to register a sample style definition.
  
<source language="js">
+
<source language="javascript">
CKEDITOR.addStylesSet( 'my_styles',
+
CKEDITOR.stylesSet.add( 'my_styles',
 
[
 
[
     // Block Styles
+
     // Block-level styles
 
     { name : 'Blue Title', element : 'h2', styles : { 'color' : 'Blue' } },
 
     { name : 'Blue Title', element : 'h2', styles : { 'color' : 'Blue' } },
 
     { name : 'Red Title' , element : 'h3', styles : { 'color' : 'Red' } },
 
     { name : 'Red Title' , element : 'h3', styles : { 'color' : 'Red' } },
  
     // Inline Styles
+
     // Inline styles
 
     { name : 'CSS Style', element : 'span', attributes : { 'class' : 'my_style' } },
 
     { name : 'CSS Style', element : 'span', attributes : { 'class' : 'my_style' } },
 
     { name : 'Marker: Yellow', element : 'span', styles : { 'background-color' : 'Yellow' } }
 
     { name : 'Marker: Yellow', element : 'span', styles : { 'background-color' : 'Yellow' } }
Line 22: Line 22:
 
</source>
 
</source>
  
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).
+
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).
  
After that, you must instruct the editor to use your newly registered style definition by using the <code>stylesCombo_stylesSet</code> setting. This may be set into the <code>config.js</code> file, for example:
+
When the definitions are ready, you must instruct the editor to apply the newly registered styles by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.stylesSet stylesSet]</code> setting. This may be set in the <code>config.js</code> file, for example:
  
<source language="js">
+
<source language="javascript">
config.stylesCombo_stylesSet = 'my_styles';
+
config.stylesSet = 'my_styles';
 
</source>
 
</source>
  
 
=== Using an External Styles Definition File ===
 
=== 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.
+
The style definition registration call can be included in an external JavaScript file. This method is a recommended one, 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, 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 <code>_source/plugins/stylescombo/styles/default.js</code>. You can see it online at our SVN also: <code>http://svn.fckeditor.net/CKEditor/trunk/_source/plugins/stylescombo/styles/default.js</code>. It can be used as a template for your custom file.
+
By default, CKEditor uses the <code>plugins/styles/styles/default.js</code> file, which is a minified JavaScript 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 <code>/styles.js</code>, or even place it in a central web site, so you can locate it with <code>http://www.example.com/styles.js</code>. At that point, simply change the <code>stylesCombo_stylesSet</code> setting to point the editor to your file:
+
The uncompressed version of this file can be found in the CKEditor package as <code>_source/plugins/styles/styles/default.js</code>. You can also see it online in our SVN repository: <code>http://svn.ckeditor.com/CKEditor/trunk/_source/plugins/styles/styles/default.js</code>. This file can be used as a template for your custom file.
  
<source language="js">
+
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 <code>/styles.js</code>, or place it anywhere else, and refer to it using its full URL, like <code><nowiki>http://www.example.com/styles.js</nowiki></code>.
config.stylesCombo_stylesSet = 'my_styles:/styles.js';
+
 
 +
At that point, change the <code>stylesSet</code> setting to point the editor to your file:
 +
 
 +
<source language="javascript">
 +
config.stylesSet = 'my_styles:/styles.js';
  
 
OR
 
OR
  
config.stylesCombo_stylesSet = 'my_styles:http://www.example.com/styles.js';
+
config.stylesSet = 'my_styles:http://www.example.com/styles.js';
 
</source>
 
</source>
  
The above setting syntax is <code>''style definition name'' : ''file URL''</code>. Note that you must still use the unique name you have used to register the style definition into the file.
+
The syntax for the style definition setting is always: <code>''style definition name'' : ''file URL''</code>.
 +
 
 +
Note that you must use the unique name you have used to register the style definition in the file.
  
 
== Style Rules  ==
 
== 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:  
+
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:  
<source language="js">
+
<source language="javascript">
 
{
 
{
     name : 'Display name',
+
     name : 'Name displayed in the Styles drop-down list',
     element : 'tag name (for example "span")',
+
     element : 'HTML element name (for example "span")',
 
     styles :
 
     styles :
 
     {
 
     {
Line 70: Line 76:
  
 
== Style Types  ==
 
== Style Types  ==
There are three types of style types, each one related to the element used in the style rule:  
+
There are three kinds of style types, each one related to the element used in the style rule:  
 +
* '''Block-level styles''' &ndash; applied to the text blocks (paragraphs) as a whole, not limited to the text selections. These apply to the following elements: <code>address</code>, <code>div</code>, <code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>, <code>h6</code>, <code>p</code>, and <code>pre</code>.
 +
* '''Object styles''' &ndash; applied to special selectable objects (not textual), whenever such selection is supported by the browser. These apply to the following elements: <code>a</code>, <code>embed</code>, <code>hr</code>, <code>img</code>, <code>li</code>, <code>object</code>, <code>ol</code>, <code>table</code>, <code>td</code>, <code>tr</code> and <code>ul</code>.
 +
* '''Inline styles''' &ndash; applied to text selections for style rules using elements not defined in other style types.
 +
 
 +
== Stylesheet Parser Plugin ==
 +
'''CKEditor 3.6''' introduced a simplified method of customizing the styles for the document created in CKEditor and populating the '''Styles''' drop-down list with style definitions added in an external CSS stylesheet file. The '''Stylesheet Parser''' plugin (<code>stylesheetparser</code>) lets you use your existing CSS styles without the need to define the styles specifically for CKEditor in the format presented above.
 +
 
 +
To use the new style definition method you need to activate the <code>stylesheetparser</code> plugin for your CKEditor instances by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.extraPlugins extraPlugins]</code> configuration setting:
 +
<source lang="javascript">
 +
config.extraPlugins = 'stylesheetparser';
 +
</source>
 +
 
 +
You then need to supply the location of the CSS file that contains your style definitions by using the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.contentsCss contentsCss]</code> configuration setting:
 +
<source lang="javascript">
 +
config.contentsCss = 'sample_CSS_file.css';
 +
</source>
 +
 
 +
Finally, if you want to skip loading the styles that are used in CKEditor by default, you may set <code>stylesSet</code> to an empty value:
 +
<source lang="javascript">
 +
config.stylesSet = [];
 +
</source>
  
* '''Block styles''' &ndash; applied to the text blocks (paragraphs) as a whole, not limited to the text selection. The elements values for that are: <code>address</code>, <code>div</code>, <code>h1</code>, <code>h2</code>, <code>h3</code>, <code>h4</code>, <code>h5</code>, <code>h6</code>, <code>p</code>, and <code>pre</code>.  
+
The new solution lets you configure the editor to use existing CSS stylesheet rules without the need to create separate style definitions for CKEditor. On the other hand, the previously used approach offers more control over which styles are available for the users, so both solutions can be employed interchangeably, according to your needs.
* '''Object styles''' &ndash; applied to special selectable objects (not textual), whenever such selection is supported by the browser. The elements values for that are: <code>a</code>, <code>embed</code>, <code>hr</code>, <code>img</code>, <code>li</code>, <code>object</code>, <code>ol</code>, <code>table</code>, <code>td</code>, <code>tr</code> and <code>ul</code>.
+
 
* '''Inline styles''' &ndash; applied to text selections for style rules using elements not defined in the other style types.
+
<note>Please note that the '''Stylesheet Parser''' plugin is available in CKEditor 3.6 and later.
 +
</note>
 +
 
 +
 
 +
For an example of this usage scenario check the "Stylesheet Parser plugin" (<code>stylesheetparser.html</code>) sample from the <code>_samples</code> folder of your CKEditor installation package.
 +
 
 +
=== Choosing the CSS Selectors ===
 +
The '''Stylesheet Parser''' plugin can be fine-tuned to only take into account the CSS selectors that match the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.stylesheetParser_validSelectors stylesheetParser_validSelectors]</code> configuration value. The default regular expression accepts all CSS rules in a form of <code>''element''.''class''</code>, but you can modify it to refer to a limited set of elements, like in the example below.
 +
 
 +
<source lang="javascript">
 +
// Only add rules for <p> and <span> elements.
 +
config.stylesheetParser_validSelectors = /\^(p|span)\.\w+/;
 +
</source>
 +
 
 +
=== Limiting the CSS Selectors ===
 +
You can also customize the default '''Stylesheet Parser''' plugin configuration by setting the <code>[http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html#.stylesheetParser_skipSelectors stylesheetParser_skipSelectors]</code> configuration value. The plugin will then ignore the CSS rules that match the regular expression and will not display them in the '''Styles''' drop-down list nor use them to output the document content. The default value excludes all rules for the <code><body></code> element as well as classes defined for no specific element, but you can modify it to ignore a wider set of elements, like in the example below.
 +
<source lang="javascript">
 +
// Ignore rules for <body> and <caption> elements, classes starting with "high", and any class defined for no specific element.
 +
config.stylesheetParser_skipSelectors = /(^body\.|^caption\.|\.high|^\.)/i;
 +
</source>

Latest revision as of 07:36, 28 June 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 a recommended one, 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 : 'Name displayed in the Styles drop-down list',
    element : 'HTML element 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 kinds of style types, each one related to the element used in the style rule:

  • Block-level styles – applied to the text blocks (paragraphs) as a whole, not limited to the text selections. These apply to the following elements: 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. These apply to the following elements: 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 other style types.

Stylesheet Parser Plugin

CKEditor 3.6 introduced a simplified method of customizing the styles for the document created in CKEditor and populating the Styles drop-down list with style definitions added in an external CSS stylesheet file. The Stylesheet Parser plugin (stylesheetparser) lets you use your existing CSS styles without the need to define the styles specifically for CKEditor in the format presented above.

To use the new style definition method you need to activate the stylesheetparser plugin for your CKEditor instances by using the extraPlugins configuration setting:

config.extraPlugins = 'stylesheetparser';

You then need to supply the location of the CSS file that contains your style definitions by using the contentsCss configuration setting:

config.contentsCss = 'sample_CSS_file.css';

Finally, if you want to skip loading the styles that are used in CKEditor by default, you may set stylesSet to an empty value:

config.stylesSet = [];

The new solution lets you configure the editor to use existing CSS stylesheet rules without the need to create separate style definitions for CKEditor. On the other hand, the previously used approach offers more control over which styles are available for the users, so both solutions can be employed interchangeably, according to your needs.

important note

Please note that the Stylesheet Parser plugin is available in CKEditor 3.6 and later.


For an example of this usage scenario check the "Stylesheet Parser plugin" (stylesheetparser.html) sample from the _samples folder of your CKEditor installation package.

Choosing the CSS Selectors

The Stylesheet Parser plugin can be fine-tuned to only take into account the CSS selectors that match the stylesheetParser_validSelectors configuration value. The default regular expression accepts all CSS rules in a form of element.class, but you can modify it to refer to a limited set of elements, like in the example below.

// Only add rules for <p> and <span> elements.
config.stylesheetParser_validSelectors = /\^(p|span)\.\w+/;

Limiting the CSS Selectors

You can also customize the default Stylesheet Parser plugin configuration by setting the stylesheetParser_skipSelectors configuration value. The plugin will then ignore the CSS rules that match the regular expression and will not display them in the Styles drop-down list nor use them to output the document content. The default value excludes all rules for the <body> element as well as classes defined for no specific element, but you can modify it to ignore a wider set of elements, like in the example below.

// Ignore rules for <body> and <caption> elements, classes starting with "high", and any class defined for no specific element.
config.stylesheetParser_skipSelectors = /(^body\.|^caption\.|\.high|^\.)/i;
This page was last edited on 28 June 2011, at 07:36.