-
- 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.
-
-
When and what is being filtered?
-
- 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.
-
-
-
How to configure or disable ACF?
-
- 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
-} );
-
-
-
Beyond data flow: Features activation
-
- 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.
-
-
-
Sample configurations
-
- There are several editor instances below that present different
- ACF setups. All of them,
- except the inline instance, share the same HTML content to visualize
- how different filtering rules affect the same input data.
-
-
-
-
-
- Editor 4:
-
-
-
- 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 .
-
-
-
-
-
-
- The below editor modify the dialog definition of the above added dialog using the dialogDefinition
event:
-
-
- Part 2
-
-
- Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Cras et ipsum quis mi
- semper accumsan. Integer pretium dui id massa. Suspendisse in nisl sit amet urna
- rutrum imperdiet. Nulla eu tellus. Donec ante nisi, ullamcorper quis, fringilla
- nec, sagittis eleifend, pede. Nulla commodo interdum massa. Donec id metus. Fusce
- eu ipsum. Suspendisse auctor. Phasellus fermentum porttitor risus.
-
-
- Donec velit. Mauris massa. Vestibulum non nulla. Nam suscipit arcu nec elit. Phasellus
- sollicitudin iaculis ante. Ut non mauris et sapien tincidunt adipiscing. Vestibulum
- vitae leo. Suspendisse nec mi tristique nulla laoreet vulputate.
-
-
-
-
- This sample shows how to configure the Enter and Shift+Enter keys
- to perform actions specified in the
- enterMode
- and shiftEnterMode
- parameters, respectively.
- You can choose from the following options:
-
-
- ENTER_P
– new <p>
paragraphs are created;
- ENTER_BR
– lines are broken with <br>
elements;
- ENTER_DIV
– new <div>
blocks are created.
-
-
- The sample code below shows how to configure CKEditor to create a <div>
block when Enter key is pressed.
-
-
-CKEDITOR.replace( 'textarea_id ', {
- enterMode: CKEDITOR.ENTER_DIV
-});
-
- Note that textarea_id
in the code above is the id
attribute of
- the <textarea>
element to be replaced.
-
-
-