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.