CKEditor 4 Documentation

CKEDITOR.style

Subclasses

Files

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

Before CKEditor 4.4 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 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.

Defined By

Properties

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

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

Defaults to: false

Available since: 4.0

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

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

Defaults to: false

Available since: 3.5

Methods

Defined By

Instance methods

CKEDITOR.style
view source
new( styleDefinition, variablesValues ) : CKEDITOR.style
Creates a style class instance. ...

Creates a style class instance.

Parameters

  • styleDefinition : Object
  • variablesValues : Object

Returns

CKEDITOR.style
view source
( editor )
Applies the style on the editor's current selection. ...

Applies the style on the editor's current selection.

Before the style is applied, the method checks if the style is applicable.

Note: The recommended way of applying the style is by using the CKEDITOR.editor.applyStyle method, which is a shorthand for this method.

Parameters

CKEDITOR.style
view source
( element, editor )
Applies the style to the element. ...

Applies the style to the element. This method bypasses all checks and applies the style attributes directly on the provided element. Use with caution.

See CKEDITOR.editor.applyStyle.

Parameters

  • element : CKEDITOR.dom.element
  • editor : CKEDITOR.editor

    The editor instance. Required argument since CKEditor 4.4. The style system will work without it, but it is highly recommended to provide it for integration with all features. Read more about the signature change in the CKEDITOR.style documentation.

CKEDITOR.style
view source
( range, editor )
Applies the style on the provided range. ...

Applies the style on the provided range. Unlike apply this method does not take care of setting the selection, however, the range is updated to the correct place.

Note: If you want to apply the style on the editor selection, you probably want to use CKEDITOR.editor.applyStyle.

Parameters

  • range : CKEDITOR.dom.range
  • editor : CKEDITOR.editor

    The editor instance. Required argument since CKEditor 4.4. The style system will work without it, but it is highly recommended to provide it for integration with all features. Read more about the signature change in the CKEDITOR.style documentation.

CKEDITOR.style
view source
( [label] ) : String
Builds the preview HTML based on the styles definition. ...

Builds the preview HTML based on the styles definition.

Parameters

  • label : String (optional)

    The label used in the style preview.

Returns

  • String

    The HTML of preview.

CKEDITOR.style
view source
( elementPath, editor ) : Boolean
Gets the style state inside the elements path. ...

Gets the style state inside the elements path.

Parameters

  • elementPath : CKEDITOR.dom.elementPath
  • editor : CKEDITOR.editor

    The editor instance. Required argument since CKEditor 4.4. The style system will work without it, but it is highly recommended to provide it for integration with all features. Read more about the signature change in the CKEDITOR.style documentation.

Returns

  • Boolean

    true if the element is active in the elements path.

CKEDITOR.style
view source
( elementPath, editor, [filter] ) : Boolean
Whether this style can be applied at the specified elements path. ...

Whether this style can be applied at the specified elements path.

Parameters

  • elementPath : CKEDITOR.dom.elementPath

    The elements path to check the style against.

  • editor : CKEDITOR.editor

    The editor instance. Required argument since CKEditor 4.4. The style system will work without it, but it is highly recommended to provide it for integration with all features. Read more about the signature change in the CKEDITOR.style documentation.

  • filter : CKEDITOR.filter (optional)

    If defined, the style will be checked against this filter as well.

Returns

  • Boolean

    true if this style can be applied at the elements path.

CKEDITOR.style
view source
( element, fullMatch, editor ) : Boolean
Checks if the element matches the current style definition. ...

Checks if the element matches the current style definition.

Parameters

  • element : CKEDITOR.dom.element
  • fullMatch : Boolean
  • editor : CKEDITOR.editor

    The editor instance. Required argument since CKEditor 4.4. The style system will work without it, but it is highly recommended to provide it for integration with all features. Read more about the signature change in the CKEDITOR.style documentation.

Returns

  • Boolean
CKEDITOR.style
view source
( element, fullMatch, editor ) : Boolean
Checks if an element, or any of its attributes, is removable by the current style definition. ...

Checks if an element, or any of its attributes, is removable by the current style definition.

Parameters

  • element : CKEDITOR.dom.element
  • fullMatch : Boolean
  • editor : CKEDITOR.editor

    The editor instance. Required argument since CKEditor 4.4. The style system will work without it, but it is highly recommended to provide it for integration with all features. Read more about the signature change in the CKEDITOR.style documentation.

Returns

  • Boolean
CKEDITOR.style
view source
( ) : Object
Returns the style definition. ...

Returns the style definition.

Available since: 4.1

Returns

  • Object
CKEDITOR.style
view source
( editor )
Removes the style from the editor's current selection. ...

Removes the style from the editor's current selection.

Before the style is applied, the method checks if style could be applied.

Note: The recommended way of removing the style is by using the CKEDITOR.editor.removeStyle method, which is a shorthand for this method.

Parameters

CKEDITOR.style
view source
( range, editor )
Removes the style from the provided range. ...

Removes the style from the provided range. Unlike remove this method does not take care of setting the selection, however, the range is updated to the correct place.

Note: If you want to remove the style from the editor selection, you probably want to use CKEDITOR.editor.removeStyle.

Parameters

  • range : CKEDITOR.dom.range
  • editor : CKEDITOR.editor

    The editor instance. Required argument since CKEditor 4.4. The style system will work without it, but it is highly recommended to provide it for integration with all features. Read more about the signature change in the CKEDITOR.style documentation.

If defined (for example by custom style handler), it returns the allowed content rules which should be added to the C...

If defined (for example by custom style handler), it returns the allowed content rules which should be added to the CKEDITOR.filter when enabling this style.

Note: This method is not defined in the CKEDITOR.style class.

Available since: 4.4

Parameters

Returns

Defined By

Static methods

CKEDITOR.style
view source
( definition ) : CKEDITOR.stylestatic
Creates a CKEDITOR.style subclass and registers it in the style system. ...

Creates a CKEDITOR.style subclass and registers it in the style system. Registered class will be used as a handler for a style of this type. This allows to extend the styles system, which by default uses only the CKEDITOR.style, with new functionality. Registered classes are accessible in the CKEDITOR.style.customHandlers.

The Style Class Definition

The definition object is used to override properties in a prototype inherited from the CKEDITOR.style class. It must contain a type property which is a name of the new type and therefore it must be unique. The default style types (STYLE_BLOCK, STYLE_INLINE, and STYLE_OBJECT) are integers, but for easier identification it is recommended to use strings as custom type names.

Besides type, the definition may contain two more special properties:

  • setup {Function} – An optional callback executed when a style instance is created. Like the style constructor, it is executed in style context and with the style definition as an argument.
  • assignedTo {Number} – Can be set to one of the default style types. Some editor features like the Styles drop-down assign styles to one of the default groups based on the style type. By using this property it is possible to notify them to which group this custom style should be assigned. It defaults to the CKEDITOR.STYLE_OBJECT.

Other properties of the definition object will just be used to extend the prototype inherited from the CKEDITOR.style class. So if the definition contains an apply method, it will override the apply method.

Usage

Registering a basic handler:

var styleClass = CKEDITOR.style.addCustomHandler( {
    type: 'custom'
} );

var style = new styleClass( { ... } );
style instanceof styleClass; // -> true
style instanceof CKEDITOR.style; // -> true
style.type; // -> 'custom'

The CKEDITOR.style constructor used as a factory:

var styleClass = CKEDITOR.style.addCustomHandler( {
    type: 'custom'
} );

// Style constructor accepts style definition (do not confuse with style class definition).
var style = new CKEDITOR.style( { type: 'custom', attributes: ... } );
style instanceof styleClass; // -> true

Thanks to that, integration code using styles does not need to know which style handler it should use. It is determined by the CKEDITOR.style constructor.

Overriding existing CKEDITOR.style methods:

var styleClass = CKEDITOR.style.addCustomHandler( {
    type: 'custom',
    apply: function( editor ) {
        console.log( 'apply' );
    },
    remove: function( editor ) {
        console.log( 'remove' );
    }
} );

var style = new CKEDITOR.style( { type: 'custom', attributes: ... } );
editor.applyStyle( style ); // logged 'apply'

style = new CKEDITOR.style( { element: 'img', attributes: { 'class': 'foo' } } );
editor.applyStyle( style ); // style is really applied if image was selected

Practical Recommendations

The style handling job, which includes such tasks as applying, removing, checking state, and checking if a style can be applied, is very complex. Therefore without deep knowledge about DOM and especially ranges and DOM walker it is impossible to implement a completely custom style handler able to handle block, inline, and object type styles. However, it is possible to customize the default implementation by overriding default methods and reusing them.

The only style handler which can be implemented from scratch without huge effort is a style applicable to objects (read more about types). Such style can only be applied when a specific object is selected. An example implementation can be found in the widget plugin.

When implementing a style handler from scratch at least the following methods must be defined:

Available since: 4.4

Parameters

  • definition : Object

    The style class definition.

Returns

  • CKEDITOR.style

    The new style class created for the provided definition.

CKEDITOR.style
view source
( styleDefinition ) : Stringstatic
Builds the inline style text based on the style definition. ...

Builds the inline style text based on the style definition.

Parameters

  • styleDefinition : Object

Returns

  • String

    Inline style text.