Report an issue
Class

CKEDITOR.filter

class since 4.1

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

Filtering

Properties

  • allowedContent : Array

    readonly

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

  • customConfig : Boolean

    readonly

    Whether custom CKEDITOR.config.allowedContent was set.

    This property does not apply to the standalone filter.

  • disabled : Boolean

    readonly

    Whether the filter is disabled.

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

    Defaults to false

  • disallowedContent : Array

    since 4.4 readonly

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

  • editor : editor

    readonly

    Editor instance if not a standalone filter.

    Defaults to null

  • elementCallbacks : Function[]

    readonly

    Array of element callbacks. See addElementCallback.

    Defaults to null

  • id : Number

    since 4.3 readonly

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

Static properties

Methods

  • constructor( editorOrRules, [ rules ] ) → filter

    Creates a filter class instance.

    Parameters

    editorOrRules : editor | allowedContentRules
    [ rules ] : allowedContentRules

    This parameter is available since 4.11.0.

    Returns

    filter
  • addContentForms( 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.

  • addElementCallback( callback )

    since 4.4

    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

    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 )

    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

    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

    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

    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

    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

    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.

  • clone() → filter

    since 4.7.3

    Returns a clone of this filter instance.

    Returns

    filter
  • destroy()

    since 4.4.5

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

  • disable()

    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.

  • disallow( newRules )

    since 4.4

    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.

  • getAllowedEnterMode( defaultMode, [ reverse ] ) → Number

    since 4.3

    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.