CKEditor 4 Documentation

CKEDITOR.filter

Files

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:

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:

Read more about the Advanced Content Filter in guides.

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

Available since: 4.1

Properties

Defined By

Instance properties

CKEDITOR.filter
view source
: Arrayreadonly
Array of rules added by the allow method (including those loaded from CKEDITOR.config.allowedContent and CKEDITOR.con...

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: []

CKEDITOR.filter
view source
: Booleanreadonly
Whether custom CKEDITOR.config.allowedContent was set. ...

Whether custom CKEDITOR.config.allowedContent was set.

This property does not apply to the standalone filter.

CKEDITOR.filter
view source
: Booleanreadonly
Whether the filter is disabled. ...

Whether the filter is disabled.

To disable the filter, set CKEDITOR.config.allowedContent to true or use the disable method.

Defaults to: false

CKEDITOR.filter
view source
: Arrayreadonly
Array of rules added by the disallow method (including those loaded from CKEDITOR.config.disallowedContent). ...

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: []

Available since: 4.4

CKEDITOR.filter
view source
: CKEDITOR.editorreadonly
Editor instance if not a standalone filter. ...

Editor instance if not a standalone filter.

Defaults to: null

CKEDITOR.filter
view source
: Function[]readonly
Array of element callbacks. ...

Array of element callbacks. See addElementCallback.

Defaults to: null

CKEDITOR.filter
view source
: Numberreadonly
Filter's unique id. ...

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

Available since: 4.3

Defined By

Static properties

CKEDITOR.filter
view source
: Objectstatic
Object containing all filter instances stored under their id properties. ...

Object containing all filter instances stored under their id properties.

var filter = new CKEDITOR.filter( 'p' );
filter === CKEDITOR.filter.instances[ filter.id ];

Defaults to: {}

Available since: 4.3

Defined By

Methods

CKEDITOR.filter
view source
new( editorOrRules ) : CKEDITOR.filter
Creates a filter class instance. ...

Creates a filter class instance.

Parameters

Returns

CKEDITOR.filter
view source
( forms )
Adds an array of CKEDITOR.feature content forms. ...

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.

CKEDITOR.filter
view source
( callback )
Adds a callback which will be executed on every element that the filter reaches when filtering, before the element is...

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.

Available since: 4.4

Parameters

  • callback : Function

    The callback to be executed.

CKEDITOR.filter
view source
( feature ) : Boolean
Checks whether a feature can be enabled for the HTML restrictions in place for the current CKEditor instance, based o...

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

Returns

  • Boolean

    Whether this feature can be enabled.

CKEDITOR.filter
view source
( transformations )
Adds an array of content transformation groups. ...

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
CKEDITOR.filter
view source
( newRules, [featureName], [overrideCustom] ) : Boolean
Adds allowed content rules to the filter. ...

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 : CKEDITOR.filter.allowedContentRules

    Rule(s) to be added.

  • featureName : String (optional)

    Name of a feature that allows this content (most often plugin/button/command name).

  • overrideCustom : Boolean (optional)

    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.

CKEDITOR.filter
view source
( fragment, [toHtml], [transformOnly], [enterMode] ) : Boolean
Applies this filter to passed CKEDITOR.htmlParser.fragment or CKEDITOR.htmlParser.element. ...

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( '<p><b>foo</b> <i>bar</i></p>' ),
    writer = new CKEDITOR.htmlParser.basicWriter();

filter.applyTo( fragment );
fragment.writeHtml( writer );
writer.getHtml(); // -> '<p><b>foo</b> bar</p>'

Parameters

Returns

  • Boolean

    Whether some part of the fragment was removed by the filter.

CKEDITOR.filter
view source
( test, [applyTransformations], [strictCheck] ) : Boolean
Checks whether the content defined in the test argument is allowed by this filter. ...

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.

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 : CKEDITOR.filter.contentRule
  • applyTransformations : Boolean (optional)

    Whether to use registered transformations.

    Defaults to: true

  • strictCheck : Boolean (optional)

    Whether the filter should check if an element with exactly these properties is allowed.

Returns

  • Boolean

    Returns true if the content is allowed.

CKEDITOR.filter
view source
( feature ) : Boolean
Checks whether a CKEDITOR.feature can be enabled. ...

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

Returns

  • Boolean

    Whether this feature can be enabled.

CKEDITOR.filter
view source
( )
Destroys the filter instance and removes it from the global instances object. ...

Destroys the filter instance and removes it from the global instances object.

Available since: 4.4.5

CKEDITOR.filter
view source
( )
Disables Advanced Content Filter. ...

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.

CKEDITOR.filter
view source
( newRules )
Adds disallowed content rules to the filter. ...

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' );

Available since: 4.4

Parameters

CKEDITOR.filter
view source
( defaultMode, [reverse] ) : Number
Returns first enter mode allowed by this filter rules. ...

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.

Available since: 4.3

Parameters

  • defaultMode : Number

    The default mode which will be checked as the first one.

  • reverse : Boolean (optional)

    Whether to check modes in reverse order (used for shift enter mode).

Returns

  • Number

    Allowed enter mode.