CKEDITOR.filter

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

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

// 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 : ArrayCKEDITOR.filter#allowedContent

  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 : BooleanCKEDITOR.filter#customConfig

  See source

  Whether custom CKEDITOR.config.allowedContent was set.

  This property does not apply to the standalone filter.

• readonly

  disabled : BooleanCKEDITOR.filter#disabled

  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 : ArrayCKEDITOR.filter#disallowedContent

  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 : editorCKEDITOR.filter#editor

  See source

  Editor instance if not a standalone filter.

  Defaults to null

• readonly

  elementCallbacks : Function[]CKEDITOR.filter#elementCallbacks

  See source

  Array of element callbacks. See addElementCallback.

  Defaults to null

• since 4.3.0 readonly

  id : NumberCKEDITOR.filter#id

  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 : ObjectCKEDITOR.filter#instances

  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 ] ) → filterCKEDITOR.filter#constructor

  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 )CKEDITOR.filter#addContentForms

  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 )CKEDITOR.filter#addElementCallback

  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 ) → BooleanCKEDITOR.filter#addFeature

  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 )CKEDITOR.filter#addTransformations

  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 ] ) → BooleanCKEDITOR.filter#allow

  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 ] ) → BooleanCKEDITOR.filter#applyTo

  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( '<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 ] ) → BooleanCKEDITOR.filter#check

  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 ) → BooleanCKEDITOR.filter#checkFeature

  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() → filterCKEDITOR.filter#clone

  See source

  Returns a clone of this filter instance.

  Returns

  filter

  since 4.4.5

  destroy()CKEDITOR.filter#destroy

  See source

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

  disable()CKEDITOR.filter#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 )CKEDITOR.filter#disallow

  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 ] ) → NumberCKEDITOR.filter#getAllowedEnterMode

  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.