CKEDITOR.style.customHandlers.widget
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
Properties
-
Indicates that any matches element of this style will be eventually removed when calling CKEDITOR.editor.removeStyle.
Defaults to
false
-
An array of groups that this style belongs to. Styles assigned to the same group cannot be combined.
-
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 inherited
unstylableElements : String[]
CKEDITOR.style.customHandlers.widget#unstylableElements
-
widget : String
CKEDITOR.style.customHandlers.widget#widget
The name of widget to which this style can be applied. It is extracted from style definition's
widget
property.
Methods
-
constructor( styleDefinition, variablesValues ) → style
CKEDITOR.style.customHandlers.widget#constructor
Creates a style class instance.
Parameters
styleDefinition : definition
variablesValues : Object
Returns
style
-
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
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.
-
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 : element
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.
-
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 : range
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.
-
Builds the preview HTML based on the styles definition.
Parameters
[ label ] : String
The label used in the style preview.
Returns
String
The HTML of preview.
-
inherited
checkActive( elementPath, editor ) → Boolean
CKEDITOR.style.customHandlers.widget#checkActive
Gets the style state inside the elements path.
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.
-
inherited
checkApplicable( elementPath, editor, [ filter ] ) → Boolean
CKEDITOR.style.customHandlers.widget#checkApplicable
Whether this style can be applied at the specified elements path.
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
CKEDITOR.style.customHandlers.widget#checkElement
Checks if an element is a wrapper of a widget whose name matches the widget name specified in the style definition.
Parameters
element : element
Returns
Boolean
-
inherited
checkElementMatch( element, fullMatch, editor ) → Boolean
CKEDITOR.style.customHandlers.widget#checkElementMatch
Checks if the element matches the current style definition.
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
-
inherited
checkElementRemovable( element, fullMatch, editor ) → Boolean
CKEDITOR.style.customHandlers.widget#checkElementRemovable
Checks if an element, or any of its attributes, is removable by the current style definition.
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[]
CKEDITOR.style.customHandlers.widget#getClassesArray
-
-
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
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.
-
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 : range
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.
-
since 4.6.2
removeStylesFromSameGroup( editor ) → Boolean
CKEDITOR.style.customHandlers.widget#removeStylesFromSameGroup
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 returnsfalse
.Parameters
editor : editor
Returns
Boolean
-
since 4.4.0 inherited
toAllowedContentRules( [ editor ] ) → allowedContentRules
CKEDITOR.style.customHandlers.widget#toAllowedContentRules
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.
Parameters
[ editor ] : editor
The editor instance.
Returns
allowedContentRules
The rules that should represent this style in the CKEDITOR.filter.
Static methods
-
since 4.4.0 inherited static
addCustomHandler( definition ) → style
CKEDITOR.style.customHandlers.widget#addCustomHandler
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:
- 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.
-
inherited static
getStyleText( styleDefinition ) → String
CKEDITOR.style.customHandlers.widget#getStyleText
Builds the inline style text based on the style definition.
Parameters
styleDefinition : Object
Returns
String
Inline style text.