Advance Content Filtering

Advance Content Filter

CKeditor 4.1 introduced advanced content filters (http://docs.ckeditor.com/#!/guide/dev_allowed_content_rules).

It allows us to determine which element and attribute combinations are allowed or disallowed in the editor's content.

This is achieve by setting the following properties:

Automatic Mode

By default Advance Content Filter(ACF) operates in automatic mode, meaning ALL elements are disallowed until explicitly allowed by a rule in enabled plugins. For example, when the image plugin is enabled, it allows the <img> tag to be used in the editor. All elements that are not allowed will be stripped from the editor's content.

Disable Advance Content Filter

Content filtering can be disabled. When disabled all tags will be allowed in the editor including <script> tags. 

//disable Advance Content Filter
config.allowedContent = true;

Allow Additional Tags

We can still take advance of the automatic mode while allowing additional tags. That is, we can have the editor only allow tags that are allowed by the enabled plugin in additional to tags that we explicitly specify. This can be achieved by settings the CKEDITOR.config.extraAllowedContent.

//These tags <dl>, <dt>, <dd> will be allowed in addition to those defined by enabled plugins.
config.extraAllowedContent = 'dl dt dd';

Disallowed Tags

We can still take advance of the automatic mode while tweaking the list of allowed tags by disabling some. This is achieved through the use of  the CKEDITOR.config.disallowedContent config.

For a complete explanation of disallowed tags see http://docs.ckeditor.com/#!/guide/dev_disallowed_content-section-how-to-allow-everything-except...

 

 config.allowedContent = 'h1 h2 h3 p';
//allowedContent will be tweaked by removing the h2 and h3 tags.
 config.disallowedContent = 'h2 h3';
 // Input:       <h1>Foo</h1><h2>Bar</h2><h3>Bom</h3>
 // Filtered:    <h1>Foo</h1><p>Bar</p><p>Bom</p>
When properties are specified on a disallowed element. Only the properties will be removed, not the complete element.A
 config.allowedContent = 'p[*]{*}(foo,bar)';
//for <p> tags, attributes starting with 'on' or has class 'foo' will be removed.
//the <p> itself will not be removed.
 config.disallowedContent = 'p[on*](foo)';
 // Input:       <p>Foo</p><p onclick="..." data-foo="1" class="foo bar">Bar</p>
 // Filtered:    <p>Foo</p><p data-foo="1" class="bar">Bar</p>

Advance Content Filter Syntax

Rules have the following syntax

elements [attributes]{styles}(classes)
  • elements – a list of space-separated element names or an asterisk (*) character,
  • attributes – a comma-separated list of attribute names or an asterisk (*) character,
  • styles – a comma-separated list of style names or an asterisk (*) character,
  • classes – a comma-separated list of classes or an asterisk (*) character.

An exclamation mark (!) used before an item name (e.g.: [!href]) in the property list means: "This property is required.". If the property isn't present for an element, ckeditor will NOT TRY to validate the element.

Sample Rules:

// A rule matching <p> and <h1> elements if they have NO properties
p h1

// A rule matching <p> and <h1> elements with optional "left" and "right" classes.
// Note: The class rule apply to both <p> and <h1>, not only <h1>.
//<p>,<h1>,<p class='left>,<h1 class='left'>,<p class='right>,<h1 class='right'>
p h1(left,right)

// A rule matching <p> and <h1> elements with (any)all attributes.
//ex. <p id='book' class='big'>,<h1 style='color:red'>
p h1[*]

// A rule match <p> and <h1> elements with all their attributes
// starting from 'data-'.
//ex. <p data-name='anne' data-age='17'><h1 data-name='bob'>
p h1[data-*]

// A rule matching <a> only if it contains the "href" attribute.
a[!href]

// A rule accepting <img> with a required "src" attribute and an optional
// "alt" attribute plus optional "width" and "height" styles.
img[alt,!src]{width,height}

//the two rule are the same regardless of white spaces and ordering
img[alt,!src]{width,height}
img { height, width } [ !src, alt ]

Set Of Rules.

Many rules can be listed on one line by seperating them with a semicolon.

// Rules allowing:
// * <p> and <h1> elements with an optional "text-align" style,
// * <a> with a required "href" attribute,
// * <strong> and <em> elements,
// * <p> with an optional "tip" class (so <p> element may contain
//  a "text-align" style and a "tip" class at the same time).
p h1{text-align}; a[!href]; strong em; p(tip)

// Rules allowing:
// * <p> and <h1> elements with an optional "id" attribute,
// * <a> with a required "href" attribute and an optional "id" attribute.
p h1; a[!href]; *[id]

Object Format

Rules may be written in an object instead of the string formats shown above.

Therefore:

allowedContent: 'p h1{text-align}; a[!href]; strong em; p(tip)'

Is equivalent to:

allowedContent: {
    'p h1': {
        styles: 'text-align'
    },
    a: {
        attributes: '!href'
    },
    'strong em': true,
    p: {
        classes: 'tip'
    }
}

Debugging

In order to verify if Allowed Content Rules were parsed correctly, you can check the CKEDITOR.filter.allowedContentproperty of the CKEDITOR.editor.filter object.

var editor = CKEDITOR.replace( 'textarea_id', {
    allowedContent: 'a[!href]; ul; li{text-align}(someclass)'
} );

editor.on( 'instanceReady', function() {
    console.log( editor.filter.allowedContent );
} );

// This will log the following array:
// { elements: 'p br', ... } (default editor rules)
// { elements: 'a', attributes: '!href' }
// { elements: 'ul' }
// { elements: 'li', styles: 'text-align', classes: 'someclass' }

 

Cookbook Category: 

Add new comment