CKEDITOR.style.customHandlers.widget

class since 4.4.0

The class representing a widget style. It is an object like the styles handler for widgets.

Note: This custom style handler does not support all methods of the CKEDITOR.style class. Not supported methods: applyToRange, removeFromRange, applyToObject.

Filtering

Public
Inherited
Mixed
Protected
Private
Deprecated

Properties

alwaysRemoveElement : Boolean

since 4.0.0

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

See source

Defaults to false
group : Array

since 4.6.2

An array of groups that this style belongs to. Styles assigned to the same group cannot be combined.

See source
includeReadonly : Boolean

since 3.5.0

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

See source

Defaults to false
widget : String

The name of widget to which this style can be applied. It is extracted from style definition's widget property.

See source

Methods

constructor( styleDefinition, variablesValues ) → style

Creates a style class instance.

See source

Parameters

styleDefinition : definition

variablesValues : Object

Returns

style
apply( editor )

Applies the style on the editor's current selection.

See source

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

editor : editor | document

The editor instance in which the style will be applied. A CKEDITOR.dom.document instance is accepted for backward compatibility reasons, although since CKEditor 4.4.0 this type of argument is deprecated. Read more about the signature change in the CKEDITOR.style documentation.
applyToObject()

Not implemented.

See source
applyToRange()

Not implemented.

See source
buildPreview( [ label ] ) → String

Builds the preview HTML based on the styles definition.

See source

Parameters

[ label ] : String

The label used in the style preview.

Returns

String

The HTML of preview.
checkActive( elementPath, editor ) → Boolean

Gets the style state inside the elements path.

See source

Parameters

elementPath : elementPath

editor : 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.
checkApplicable( elementPath, editor, [ filter ] ) → Boolean

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

See source

Parameters

elementPath : elementPath

The elements path to check the style against.

editor : 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 ] : filter

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.
checkElement( element ) → Boolean

Checks if an element is a wrapper of a widget whose name matches the widget name specified in the style definition.

See source

Parameters

element : element

Returns

Boolean
checkElementMatch( element, fullMatch, editor ) → Boolean

Checks if the element matches the current style definition.

See source

Parameters

element : element

fullMatch : Boolean

editor : 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
checkElementRemovable( element, fullMatch, editor ) → Boolean

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

See source

Parameters

element : element

fullMatch : Boolean

editor : 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
getClassesArray() → String[]

Returns classes defined in the style in form of an array.

See source

Returns

String[]
getDefinition() → Object

since 4.1.0

Returns the style definition.

See source

Returns

Object
remove( editor )

Removes the style from the editor's current selection.

See source

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

editor : editor | document

The editor instance in which the style will be removed. A CKEDITOR.dom.document instance is accepted for backward compatibility reasons, although since CKEditor 4.4.0 this type of argument is deprecated. Read more about the signature change in the CKEDITOR.style documentation.
removeFromRange()

Not implemented.

See source
removeStylesFromSameGroup( editor ) → Boolean

since 4.6.2

Removes all styles that belong to the same group as this style. This method will neither add nor remove the current style. Returns true if any style was removed, otherwise returns false.

See source

Parameters

editor : editor

Returns

Boolean
toAllowedContentRules( The ) → allowedContentRules

Returns allowed content rules which should be registered for this style. Uses widget's CKEDITOR.plugins.widget.definition.styleableElements to make a rule allowing classes on specified elements or use widget's CKEDITOR.plugins.widget.definition.styleToAllowedContentRules method to transform a style into allowed content rules.

See source

Parameters

The : editor

editor instance.

Returns

allowedContentRules

Static methods

addCustomHandler( definition ) → style

since 4.4.0 inherited static
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.

See source
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:
- apply and remove,
- checkElementRemovable and checkElementMatch – Note that both methods reuse the same logic,
- checkActive – Reuses checkElementMatch,
- toAllowedContentRules – Not required, but very useful in case of a custom style that has to notify the CKEDITOR.filter which rules it allows when registered.
Parameters

definition : Object

The style class definition.

Returns

style

The new style class created for the provided definition.
getStyleText( styleDefinition ) → String

inherited static

Builds the inline style text based on the style definition.

See source

Parameters

styleDefinition : Object

Returns

String

Inline style text.

CKEDITOR.style.customHandlers.widget

Filtering

Properties

alwaysRemoveElement : BooleanCKEDITOR.style.customHandlers.widget#alwaysRemoveElement

group : ArrayCKEDITOR.style.customHandlers.widget#group

includeReadonly : BooleanCKEDITOR.style.customHandlers.widget#includeReadonly

widget : StringCKEDITOR.style.customHandlers.widget#widget

Methods

constructor( styleDefinition, variablesValues ) → styleCKEDITOR.style.customHandlers.widget#constructor

Parameters

Returns

apply( editor )CKEDITOR.style.customHandlers.widget#apply

Parameters

applyToObject()CKEDITOR.style.customHandlers.widget#applyToObject

applyToRange()CKEDITOR.style.customHandlers.widget#applyToRange

buildPreview( [ label ] ) → StringCKEDITOR.style.customHandlers.widget#buildPreview

Parameters

Returns

checkActive( elementPath, editor ) → BooleanCKEDITOR.style.customHandlers.widget#checkActive

Parameters

Returns

checkApplicable( elementPath, editor, [ filter ] ) → BooleanCKEDITOR.style.customHandlers.widget#checkApplicable

Parameters

Returns

checkElement( element ) → BooleanCKEDITOR.style.customHandlers.widget#checkElement

Parameters

Returns

checkElementMatch( element, fullMatch, editor ) → BooleanCKEDITOR.style.customHandlers.widget#checkElementMatch

Parameters

Returns

checkElementRemovable( element, fullMatch, editor ) → BooleanCKEDITOR.style.customHandlers.widget#checkElementRemovable

Parameters

Returns

getClassesArray() → String[]CKEDITOR.style.customHandlers.widget#getClassesArray

Returns

getDefinition() → ObjectCKEDITOR.style.customHandlers.widget#getDefinition

Returns

remove( editor )CKEDITOR.style.customHandlers.widget#remove

Parameters

removeFromRange()CKEDITOR.style.customHandlers.widget#removeFromRange

removeStylesFromSameGroup( editor ) → BooleanCKEDITOR.style.customHandlers.widget#removeStylesFromSameGroup

Parameters

Returns

toAllowedContentRules( The ) → allowedContentRulesCKEDITOR.style.customHandlers.widget#toAllowedContentRules

Parameters

Returns

Static methods

addCustomHandler( definition ) → styleCKEDITOR.style.customHandlers.widget#addCustomHandler

The Style Class Definition

Usage

Practical Recommendations

Parameters

Returns

getStyleText( styleDefinition ) → StringCKEDITOR.style.customHandlers.widget#getStyleText

Parameters

Returns

`alwaysRemoveElement : Boolean`

`group : Array`

`includeReadonly : Boolean`

`widget : String`

`constructor( styleDefinition, variablesValues ) → style`

`apply( editor )`

`applyToObject()`

`applyToRange()`

`buildPreview( [ label ] ) → String`

`checkActive( elementPath, editor ) → Boolean`

`checkApplicable( elementPath, editor, [ filter ] ) → Boolean`

`checkElement( element ) → Boolean`

`checkElementMatch( element, fullMatch, editor ) → Boolean`

`checkElementRemovable( element, fullMatch, editor ) → Boolean`

`getClassesArray() → String[]`

`getDefinition() → Object`

`remove( editor )`

`removeFromRange()`

`removeStylesFromSameGroup( editor ) → Boolean`

`toAllowedContentRules( The ) → allowedContentRules`

`addCustomHandler( definition ) → style`

`getStyleText( styleDefinition ) → String`