CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 4/API
Class

CKEDITOR.style

class
See source

A class representing a style instance for the specific style definition. In this approach, a style is a set of properties, like attributes and styles, which can be applied to and removed from a selection through editor methods: CKEDITOR.editor.applyStyle and CKEDITOR.editor.removeStyle, respectively.

Three default style types are available: STYLE_BLOCK, STYLE_INLINE, and STYLE_OBJECT. Based on its type, a style heavily changes its behavior. You can read more about style types in the Style Types section of the Styles guide.

It is possible to define a custom style type by subclassing this class by using the addCustomHandler method. However, because of great complexity of the styles handling job, it is only possible in very specific cases.

Usage

Basic usage:

// Define a block style.
var style = new CKEDITOR.style( { element: 'h1' } );

// Considering the following selection:
// <p>Foo</p><p>Bar^</p>
// Executing:
editor.applyStyle( style );
// Will give:
// <p>Foo</p><h1>Bar^</h1>
style.checkActive( editor.elementPath(), editor ); // -> true

editor.removeStyle( style );
// Will give:
// <p>Foo</p><p>Bar^</p>

style.checkActive( editor.elementPath(), editor ); // -> false

Object style:

// Define an object style.
var style = new CKEDITOR.style( { element: 'img', attributes: { 'class': 'foo' } } );

// Considering the following selection:
// <p><img src="bar.png" alt="" />Foo^</p>
// Executing:
editor.applyStyle( style );
// Will not apply the style, because the image is not selected.
// You can check if a style can be applied on the current selection with:
style.checkApplicable( editor.elementPath(), editor ); // -> false

// Considering the following selection:
// <p>[<img src="bar.png" alt="" />]Foo</p>
// Executing
editor.applyStyle( style );
// Will give:
// <p>[<img src="bar.png" alt="" class="foo" />]Foo</p>
API changes introduced in CKEditor 4.4.0

Before CKEditor 4.4.0 all style instances had no access at all to the editor instance within which the style is used. Neither the style constructor, nor style methods were requiring passing the editor instance which made styles independent of the editor and hence its settings and state. This design decision came from CKEditor 3; it started causing problems and became an unsolvable obstacle for the widget style handler which we introduced in CKEditor 4.4.

There were two possible solutions. Passing an editor instance to the style constructor or to every method. The first approach would be clean, however, having in mind the backward compatibility, we did not decide to go for it. It would bind the style to one editor instance, making it unusable with other editor instances. That could break many implementations reusing styles between editors. Therefore, we decided to take the longer but safer path — the editor instance became an argument for nearly all style methods, however, for backward compatibility reasons, all these methods will work without it. Even the newly implemented widget style handler's methods will not fail, although they will also not work by aborting at an early stage.

Therefore, you can safely upgrade to CKEditor 4.4.0 even if you use style methods without providing the editor instance. You must only align your code if your implementation should handle widget styles or any other custom style handler. Of course, we recommend doing this in any case to avoid potential problems in the future.

Filtering

Properties

  • since 4.0.0

    alwaysRemoveElement : Boolean

    See source

    Indicates that any matches element of this style will be eventually removed when calling CKEDITOR.editor.removeStyle.

    Defaults to false

  • since 3.5.0

    includeReadonly : Boolean

    See source

    Indicates that fully selected read-only elements will be included when applying the style (for inline styles only).

    Defaults to false

  • since 4.15.0

    unstylableElements : String[]

    See source

    List of all elements that are ignored during styling.

    Defaults to []

Methods