CKEDITOR.filter

classsince 4.1.0

Highly configurable class which implements input data filtering mechanisms and core functions used for the activation of editor features.

A filter instance is always available under the CKEDITOR.editor.filter property and is used by the editor in its core features like filtering input data, applying data transformations, validating whether a feature may be enabled for the current setup. It may be configured in two ways:

By the user, with the CKEDITOR.config.allowedContent setting.
Automatically, by loaded features (toolbar items, commands, etc.).

In both cases additional allowed content rules may be added by setting the CKEDITOR.config.extraAllowedContent configuration option.

Note: Filter rules will be extended with the following elements depending on the CKEDITOR.config.enterMode and CKEDITOR.config.shiftEnterMode settings:

'p' – for CKEDITOR.ENTER_P,
'div' – for CKEDITOR.ENTER_DIV,
'br' – for CKEDITOR.ENTER_BR.

Read more about Advanced Content Filter in guides.

A filter may also be used as a standalone instance by passing CKEDITOR.filter.allowedContentRules instead of CKEDITOR.editor to the constructor:

var filter = new CKEDITOR.filter( 'b' );

filter.check( 'b' ); // -> true
filter.check( 'i' ); // -> false
filter.allow( 'i' );
filter.check( 'i' ); // -> true

If the filter is only used by a single editor instance, you should pass the editor instance alongside with the rules. Passing the editor as the first parameter binds it with the filter so the filter can be removed with the CKEDITOR.editor.destroy method to prevent memory leaks.

// In both cases the filter will be removed during the CKEDITOR.editor.destroy function execution.
var filter1 = new CKEDITOR.filter( editor );
var filter2 = new CKEDITOR.filter( editor, 'b' );

Properties

readonly
allowedContent : Array

See source
Array of rules added by the allow method (including those loaded from CKEDITOR.config.allowedContent and CKEDITOR.config.extraAllowedContent).
Rules in this array are in unified allowed content rules format.
This property is useful for debugging issues with rules string parsing or for checking which rules were automatically added by editor features.
Defaults to []
readonly
customConfig : Boolean

See source
Whether custom CKEDITOR.config.allowedContent was set.
This property does not apply to the standalone filter.
readonly
disabled : Boolean

See source
Whether the filter is disabled.
To disable the filter, set CKEDITOR.config.allowedContent to true or use the disable method.
Defaults to false
since 4.4.0 readonly
disallowedContent : Array

See source
Array of rules added by the disallow method (including those loaded from CKEDITOR.config.disallowedContent).
Rules in this array are in unified disallowed content rules format.
This property is useful for debugging issues with rules string parsing or for checking which rules were automatically added by editor features.
Defaults to []
readonly
editor : editor

See source
Editor instance if not a standalone filter.
Defaults to null
readonly
elementCallbacks : Function[]

See source
Array of element callbacks. See addElementCallback.
Defaults to null
since 4.3.0 readonly
id : Number

See source
Filter's unique id. It can be used to find filter instance in CKEDITOR.filter.instance object.

Static properties

since 4.3.0 static
instances : Object
See source
Object containing all filter instances stored under their id properties.
```
var filter = new CKEDITOR.filter( 'p' );
filter === CKEDITOR.filter.instances[ filter.id ];
```
Defaults to {}

Methods

constructor( editorOrRules, [ rules ] ) → filter

See source
Creates a filter class instance.
Parameters
editorOrRules : editor | allowedContentRules
[ rules ] : allowedContentRules
This parameter is available since 4.11.0.
Returns
filter

`addContentForms( forms )`

See source

Adds an array of CKEDITOR.feature content forms. All forms will then be transformed to the first form which is allowed by the filter.

editor.filter.allow( 'i; span{!font-style}' );
editor.filter.addContentForms( [
    'em',
    'i',
    [ 'span', function( el ) {
        return el.styles[ 'font-style' ] == 'italic';
    } ]
] );
// Now <em> and <span style="font-style:italic"> will be replaced with <i>
// because this is the first allowed form.
// <span> is allowed too, but it is the last form and
// additionaly, the editor cannot transform an element based on
// the array+function form).

This method is used by the editor to register CKEDITOR.feature.contentForms when adding a feature with addFeature or CKEDITOR.editor.addFeature.

Parameters

forms : Array: The content forms of a feature.

since 4.4.0
addElementCallback( callback )
See source
Adds a callback which will be executed on every element that the filter reaches when filtering, before the element is filtered.
By returning CKEDITOR.FILTER_SKIP_TREE it is possible to skip filtering of the current element and all its ancestors.
```
editor.filter.addElementCallback( function( el ) {
    if ( el.hasClass( 'protected' ) )
        return CKEDITOR.FILTER_SKIP_TREE;
} );
```
Note: At this stage the element passed to the callback does not contain attributes, classes, and styles properties which are available temporarily on later stages of the filtering process. Therefore you need to use the pure CKEDITOR.htmlParser.element interface.
Parameters
callback : Function
The callback to be executed.
addFeature( feature ) → Boolean
See source
Checks whether a feature can be enabled for the HTML restrictions in place for the current CKEditor instance, based on the HTML code the feature might generate and the minimal HTML code the feature needs to be able to generate.
```
// TODO example
```
Parameters
feature : feature
Returns
Boolean
Whether this feature can be enabled.

`addTransformations( transformations )`

See source

Adds an array of content transformation groups. One group may contain many transformation rules, but only the first matching rule in a group is executed.

A single transformation rule is an object with four properties:

check (optional) – if set and CKEDITOR.filter does not accept this CKEDITOR.filter.contentRule, this transformation rule will not be executed (it does not match). This value is passed to check.
element (optional) – this string property tells the filter on which element this transformation can be run. It is optional, because the element name can be obtained from check (if it is a String format) or left (if it is a CKEDITOR.style instance).
left (optional) – a function accepting an element or a CKEDITOR.style instance verifying whether the transformation should be executed on this specific element. If it returns false or if an element does not match this style, this transformation rule does not match.
right – a function accepting an element and CKEDITOR.filter.transformationsTools or a string containing the name of the CKEDITOR.filter.transformationsTools method that should be called on an element.

A shorthand format is also available. A transformation rule can be defined by a single string 'check:right'. The string before ':' will be used as the check property and the second part as the right property.

Transformation rules can be grouped. The filter will try to apply the first rule in a group. If it matches, the filter will ignore subsequent rules and will move to the next group. If it does not match, the next rule will be checked.

Examples:

editor.filter.addTransformations( [
    // First group.
    [
        // First rule. If table{width} is allowed, it
        // executes CKEDITOR.filter.transformationsTools.sizeToStyle on a table element.
        'table{width}: sizeToStyle',
        // Second rule should not be executed if the first was.
        'table[width]: sizeToAttribute'
    ],
    // Second group.
    [
        // This rule will add the foo="1" attribute to all images that
        // do not have it.
        {
            element: 'img',
            left: function( el ) {
                return !el.attributes.foo;
            },
            right: function( el, tools ) {
                el.attributes.foo = '1';
            }
        }
    ]
] );

// Case 1:
// config.allowedContent = 'table{height,width}; tr td'.
//
// '<table style="height:100px; width:200px">...</table>'       -> '<table style="height:100px; width:200px">...</table>'
// '<table height="100" width="200">...</table>'                -> '<table style="height:100px; width:200px">...</table>'

// Case 2:
// config.allowedContent = 'table[height,width]; tr td'.
//
// '<table style="height:100px; width:200px">...</table>'       -> '<table height="100" width="200">...</table>'
// '<table height="100" width="200">...</table>'                -> '<table height="100" width="200"">...</table>'

// Case 3:
// config.allowedContent = 'table{width,height}[height,width]; tr td'.
//
// '<table style="height:100px; width:200px">...</table>'       -> '<table style="height:100px; width:200px">...</table>'
// '<table height="100" width="200">...</table>'                -> '<table style="height:100px; width:200px">...</table>'
//
// Note: Both forms are allowed (size set by style and by attributes), but only
// the first transformation is applied &mdash; the size is always transformed to a style.
// This is because only the first transformation matching allowed content rules is applied.

This method is used by the editor to add CKEDITOR.feature.contentTransformations when adding a feature by addFeature or CKEDITOR.editor.addFeature.

Parameters

transformations : Array

allow( newRules, [ featureName ], [ overrideCustom ] ) → Boolean
See source
Adds allowed content rules to the filter.
Read about rules formats in Allowed Content Rules guide.
```
// Add a basic rule for custom image feature (e.g. 'MyImage' button).
editor.filter.allow( 'img[!src,alt]', 'MyImage' );

// Add rules for two header styles allowed by 'HeadersCombo'.
var header1Style = new CKEDITOR.style( { element: 'h1' } ),
    header2Style = new CKEDITOR.style( { element: 'h2' } );
editor.filter.allow( [ header1Style, header2Style ], 'HeadersCombo' );
```
Parameters
newRules : allowedContentRules
Rule(s) to be added.
[ featureName ] : String
Name of a feature that allows this content (most often plugin/button/command name).
[ overrideCustom ] : Boolean
By default this method will reject any rules if CKEDITOR.config.allowedContent is defined to avoid overriding it. Pass true to force rules addition.
Returns
Boolean
Whether the rules were accepted.
applyTo( fragment, [ toHtml ], [ transformOnly ], [ enterMode ] ) → Boolean
See source
Applies this filter to passed CKEDITOR.htmlParser.fragment or CKEDITOR.htmlParser.element. The result of filtering is a DOM tree without disallowed content.
```
 // Create standalone filter passing 'p' and 'b' elements.
var filter = new CKEDITOR.filter( 'p b' ),
 // Parse HTML string to pseudo DOM structure.
 fragment = CKEDITOR.htmlParser.fragment.fromHtml( 'foo bar' ),
 writer = new CKEDITOR.htmlParser.basicWriter();

filter.applyTo( fragment );
fragment.writeHtml( writer );
writer.getHtml(); // -> 'foo bar'
```
Parameters
fragment : fragment | element
Node to be filtered.
[ toHtml ] : Boolean
Set to true if the filter is used together with CKEDITOR.htmlDataProcessor.toHtml.
[ transformOnly ] : Boolean
If set to true only transformations will be applied. Content will not be filtered with allowed content rules.
[ enterMode ] : Number
Enter mode used by the filter when deciding how to strip disallowed element. Defaults to CKEDITOR.editor.activeEnterMode for a editor's filter or to CKEDITOR.ENTER_P for standalone filter.
Returns
Boolean
Whether some part of the fragment was removed by the filter.
check( test, [ applyTransformations ], [ strictCheck ] ) → Boolean
See source
Checks whether the content defined in the test argument is allowed by this filter.
If strictCheck is set to false (default value), this method checks if all parts of the test (styles, attributes, and classes) are accepted by the filter. If strictCheck is set to true, the test must also contain the required attributes, styles, and classes.
For example:
```
// Rule: 'img[!src,alt]'.
filter.check( 'img[alt]' ); // -> true
filter.check( 'img[alt]', true, true ); // -> false
```
Second check() call returned false because src is required.
When an array of rules is passed as the test argument, the filter returns true if at least one of the passed rules is allowed.
For example:
```
// Rule: 'img'
filter.check( [ 'img', 'div' ] ) // -> true
filter.check( [ 'p', 'div' ] ) // -> false
```
Note: The test argument is of CKEDITOR.filter.contentRule type, which is a limited version of CKEDITOR.filter.allowedContentRules. Read more about it in the CKEDITOR.filter.contentRule's documentation.
Parameters
test : contentRule | contentRule[]
[ applyTransformations ] : Boolean
Whether to use registered transformations.

Defaults to true
[ strictCheck ] : Boolean
Whether the filter should check if an element with exactly these properties is allowed.
Returns
Boolean
Returns true if the content is allowed.
checkFeature( feature ) → Boolean
See source
Checks whether a CKEDITOR.feature can be enabled. Unlike addFeature, this method always checks the feature, even when the default configuration for CKEDITOR.config.allowedContent is used.
```
// TODO example
```
Parameters
feature : feature
The feature to be tested.
Returns
Boolean
Whether this feature can be enabled.
since 4.7.3
clone() → filter

See source
Returns a clone of this filter instance.
Returns
filter
since 4.4.5
destroy()

See source
Destroys the filter instance and removes it from the global instances object.
disable()

See source
Disables Advanced Content Filter.
This method is meant to be used by plugins which are not compatible with the filter and in other cases in which the filter has to be disabled during the initialization phase or runtime.
In other cases the filter can be disabled by setting CKEDITOR.config.allowedContent to true.
since 4.4.0
disallow( newRules )
See source
Adds disallowed content rules to the filter.
Read about rules formats in the Allowed Content Rules guide.
```
// Disallow all styles on the image elements.
editor.filter.disallow( 'img{*}' );

// Disallow all span and div elements.
editor.filter.disallow( 'span div' );
```
Parameters
newRules : disallowedContentRules
Rule(s) to be added.
since 4.3.0
getAllowedEnterMode( defaultMode, [ reverse ] ) → Number

See source
Returns first enter mode allowed by this filter rules. Modes are checked in p, div, br order. If none of tags is allowed this method will return CKEDITOR.ENTER_BR.
Parameters
defaultMode : Number
The default mode which will be checked as the first one.
[ reverse ] : Boolean
Whether to check modes in reverse order (used for shift enter mode).
Returns
Number
Allowed enter mode.

CKEDITOR.filter

Filtering

Properties

readonlyallowedContent : ArrayCKEDITOR.filter#allowedContent

readonlycustomConfig : BooleanCKEDITOR.filter#customConfig

readonlydisabled : BooleanCKEDITOR.filter#disabled

since 4.4.0 readonlydisallowedContent : ArrayCKEDITOR.filter#disallowedContent

readonlyeditor : editorCKEDITOR.filter#editor

readonlyelementCallbacks : Function[]CKEDITOR.filter#elementCallbacks

since 4.3.0 readonlyid : NumberCKEDITOR.filter#id

Static properties

since 4.3.0 staticinstances : ObjectCKEDITOR.filter#instances

Methods

constructor( editorOrRules, [ rules ] ) → filterCKEDITOR.filter#constructor

Parameters

Returns

addContentForms( forms )CKEDITOR.filter#addContentForms

Parameters

since 4.4.0addElementCallback( callback )CKEDITOR.filter#addElementCallback

Parameters

addFeature( feature ) → BooleanCKEDITOR.filter#addFeature

Parameters

Returns

addTransformations( transformations )CKEDITOR.filter#addTransformations

Parameters

allow( newRules, [ featureName ], [ overrideCustom ] ) → BooleanCKEDITOR.filter#allow

Parameters

Returns

applyTo( fragment, [ toHtml ], [ transformOnly ], [ enterMode ] ) → BooleanCKEDITOR.filter#applyTo

Parameters

Returns

check( test, [ applyTransformations ], [ strictCheck ] ) → BooleanCKEDITOR.filter#check

Parameters

Returns

checkFeature( feature ) → BooleanCKEDITOR.filter#checkFeature

Parameters

Returns

since 4.7.3clone() → filterCKEDITOR.filter#clone

Returns

since 4.4.5destroy()CKEDITOR.filter#destroy

disable()CKEDITOR.filter#disable

since 4.4.0disallow( newRules )CKEDITOR.filter#disallow

Parameters

since 4.3.0getAllowedEnterMode( defaultMode, [ reverse ] ) → NumberCKEDITOR.filter#getAllowedEnterMode

Parameters

Returns

readonly
`allowedContent : Array`

readonly
`customConfig : Boolean`

readonly
`disabled : Boolean`

since 4.4.0 readonly
`disallowedContent : Array`

readonly
`editor : editor`

readonly
`elementCallbacks : Function[]`

since 4.3.0 readonly
`id : Number`

since 4.3.0 static
`instances : Object`

`constructor( editorOrRules, [ rules ] ) → filter`

`addContentForms( forms )`

since 4.4.0
`addElementCallback( callback )`

`addFeature( feature ) → Boolean`

`addTransformations( transformations )`

`allow( newRules, [ featureName ], [ overrideCustom ] ) → Boolean`

`applyTo( fragment, [ toHtml ], [ transformOnly ], [ enterMode ] ) → Boolean`

`check( test, [ applyTransformations ], [ strictCheck ] ) → Boolean`

`checkFeature( feature ) → Boolean`

since 4.7.3
`clone() → filter`

since 4.4.5
`destroy()`

`disable()`

since 4.4.0
`disallow( newRules )`

since 4.3.0
`getAllowedEnterMode( defaultMode, [ reverse ] ) → Number`