- This sample page demonstrates the idea of Advanced Content Filter - (ACF), a sophisticated - tool that takes control over what kind of data is accepted by the editor and what - kind of output is produced. -
-- ACF controls - every single source of data that comes to the editor. - It process both HTML that is inserted manually (i.e. pasted by the user) - and programmatically like: -
--editor.setData( '<p>Hello world!</p>' ); --
- ACF discards invalid, - useless HTML tags and attributes so the editor remains "clean" during - runtime. ACF behaviour - can be configured and adjusted for a particular case to prevent the - output HTML (i.e. in CMS systems) from being polluted. - - This kind of filtering is a first, client-side line of defense - against "tag soups", - the tool that precisely restricts which tags, attributes and styles - are allowed (desired). When properly configured, ACF - is an easy and fast way to produce a high-quality, intentionally filtered HTML. -
- -
- Advanced Content Filter is enabled by default, working in "automatic mode", yet
- it provides a set of easy rules that allow adjusting filtering rules
- and disabling the entire feature when necessary. The config property
- responsible for this feature is config.allowedContent.
-
- By "automatic mode" is meant that loaded plugins decide which kind
- of content is enabled and which is not. For example, if the link
- plugin is loaded it implies that <a> tag is
- automatically allowed. Each plugin is given a set
- of predefined ACF rules
- that control the editor until
- config.allowedContent
- is defined manually.
-
- Let's assume our intention is to restrict the editor to accept (produce) paragraphs
- only: no attributes, no styles, no other tags.
- With ACF
- this is very simple. Basically set
- config.allowedContent to 'p':
-
-var editor = CKEDITOR.replace( textarea_id, {
- allowedContent: 'p'
-} );
-
- - Now try to play with allowed content: -
--// Trying to insert disallowed tag and attribute. -editor.setData( '<p style="color: red">Hello <em>world</em>!</p>' ); -alert( editor.getData() ); - -// Filtered data is returned. -"<p>Hello world!</p>" --
- What happened? Since config.allowedContent: 'p' is set the editor assumes
- that only plain <p> are accepted. Nothing more. This is why
- style attribute and <em> tag are gone. The same
- filtering would happen if we pasted disallowed HTML into this editor.
-
- This is just a small sample of what ACF - can do. To know more, please refer to the sample section below and - the official Advanced Content Filter guide. -
-
- You may, of course, want CKEditor to avoid filtering of any kind.
- To get rid of ACF,
- basically set
- config.allowedContent to true like this:
-
-CKEDITOR.replace( textarea_id, {
- allowedContent: true
-} );
-
-
-
- ACF is far more than
- I/O control: the entire
- UI of the editor is adjusted to what
- filters restrict. For example: if <a> tag is
- disallowed
- by ACF,
- then accordingly link command, toolbar button and link dialog
- are also disabled. Editor is smart: it knows which features must be
- removed from the interface to match filtering rules.
-
- CKEditor can be far more specific. If <a> tag is
- allowed by filtering rules to be used but it is restricted
- to have only one attribute (href)
- config.allowedContent = 'a[!href]', then
- "Target" tab of the link dialog is automatically disabled as target
- attribute isn't included in ACF rules
- for <a>. This behaviour applies to dialog fields, context
- menus and toolbar buttons.
-
- There are several editor instances below that present different - ACF setups. All of them, - except the last inline instance, share the same HTML content to visualize - how different filtering rules affect the same input data. -
-
- This editor is using default configuration ("automatic mode"). It means that
-
- config.allowedContent is defined by loaded plugins.
- Each plugin extends filtering rules to make it's own associated content
- available for the user.
-
- This editor is using a custom configuration for - ACF: -
-
-CKEDITOR.replace( 'editor2', {
- allowedContent:
- 'h1 h2 h3 p blockquote strong em;' +
- 'a[!href];' +
- 'img(left,right)[!src,alt,width,height];' +
- 'table tr th td caption;' +
- 'span{!font-family};' +'
- 'span{!color};' +
- 'span(!marker);' +
- 'del ins'
-} );
-
- - The following rules may require additional explanation: -
-h1 h2 h3 p blockquote strong em - These tags
- are accepted by the editor. Any tag attributes will be discarded.
- a[!href] - href attribute is obligatory
- for <a> tag. Tags without this attribute
- are disarded. No other attribute will be accepted.
- img(left,right)[!src,alt,width,height] - src
- attribute is obligatory for <img> tag.
- alt, width, height
- and class attributes are accepted but
- class must be either class="left"
- or class="right"
- table tr th td caption - These tags
- are accepted by the editor. Any tag attributes will be discarded.
- span{!font-family}, span{!color},
- span(!marker) - <span> tags
- will be accepted if either font-family or
- color style is set or class="marker"
- is present.
- del ins - These tags
- are accepted by the editor. Any tag attributes will be discarded.
-
- Please note that UI of the
- editor is different. It's a response to what happened to the filters.
- Since text-align isn't allowed, the align toolbar is gone.
- The same thing happened to subscript/superscript, strike, underline
- (<u>, <sub>, <sup>
- are disallowed by
- config.allowedContent) and many other buttons.
-
- This editor is using a custom configuration for - ACF. - Note that filters can be configured as an object literal - as an alternative to a string-based definition. -
-
-CKEDITOR.replace( 'editor3', {
- allowedContent: {
- 'b i ul ol big small': true,
- 'h1 h2 h3 p blockquote li': {
- styles: 'text-align'
- },
- a: { attributes: '!href,target' },
- img: {
- attributes: '!src,alt',
- styles: 'width,height',
- classes: 'left,right'
- }
- }
-} );
-
- - This editor is using a custom set of plugins and buttons. -
-
-CKEDITOR.replace( 'editor4', {
- removePlugins: 'bidi,font,forms,flash,horizontalrule,iframe,justify,table,tabletools,smiley',
- removeButtons: 'Anchor,Underline,Strike,Subscript,Superscript,Image',
- format_tags: 'p;h1;h2;h3;pre;address'
-} );
-
-
- As you can see, removing plugins and buttons implies filtering.
- Several tags are not allowed in the editor because there's no
- plugin/button that is responsible for creating and editing this
- kind of content (for example: the image is missing because
- of removeButtons: 'Image'). The conclusion is that
- ACF works "backwards"
- as well: modifying UI
- elements is changing allowed content rules.
-
- This editor is built on editable <h1> element.
- ACF takes care of
- what can be included in <h1>. Note that there
- are no block styles in Styles combo. Also why lists, indentation,
- blockquote, div, form and other buttons are missing.
-
- ACF makes sure that
- no disallowed tags will come to <h1> so the final
- markup is valid. If the user tried to paste some invalid HTML
- into this editor (let's say a list), it would be automatically
- converted into plain text.
-