Upgrading to CKEditor 4.1

CKEditor 4.1 introduced an innovative set of features that we dubbed Advanced Content Filter (ACF in short). These features change the way that the editor deals with input data, so upgrading to version 4.1 requires some understanding of what has changed. More importantly, you will need to take into account the fact that since CKEditor 4.1 content filtering is now turned on by default and will affect all data that is input into the editor, including content created in the past and stored in your database or website. Failure to understand what ACF is about and incorrect ACF implementation might result in data loss.

To make the upgrade process easier here are a few tips that you should keep in mind.

Read the Documentation

We have created quite a lot of resources regarding Advanced Content Filter and there is no better way to start than reading the docs. Here are a few links that you can refer to:

• The blog post introducing CKEditor 4.1 Release Candidate with a nice introduction into ACF, explaining why content filtering is exactly the thing you have been waiting for.

• The CKEditor 4.1 release post.

• The Advanced Content Filter chapter of the Developer's Guide.

• The datafiltering.html sample available in the samples folder of each CKEditor installation package.

• The data filtering demo on our website.

Check Plugin Compatibility

All plugins that create editor content should now be compatible with Advanced Content Filter. We took care of all official CKSource plugins*, so you can be sure they will work, but if you created your custom plugins, you will need to update their code in order to integrate with ACF. Likewise, if you want to add some third-party plugins from the Add-on Repository to your editor configuration, make sure they have already been updated or urge their authors to do so.

* The only exception is the Content Templates plugin that cannot be automatically integrated with ACF. If you want to utilize templates, use the config.extraAllowedContent to add the unsupported elements or disable ACF by setting config.allowedContent = true. Additionally, the BBCode and Styles Parser plugins turn ACF off.

ACF Test Snippet

If you have any doubts as to whether your integration with Advanced Content Filter is complete, you can use the attached JavaScript snippet. This code should be inserted into your code directly below the <script> tag that includes ckeditor.js. If incoming data is filtered, the JavaScript console will inform you about this fact.

CKEDITOR.on( 'instanceCreated', function( event ) {
	var editor = event.editor,
		originalData,
		listener,
		dataFiltered = false;

	// Save originally loaded data.
	editor.on( 'loaded', function() {
		originalData = editor.getData( true );
	} );

	// The 'dataFiltered' event is fired when data (loaded, pasted,
	// or inserted in other ways) is filtered 
	// by Advanced Content Filter.
	listener = editor.on( 'dataFiltered', function() {
		dataFiltered = true;
	} );

	editor.on( 'instanceReady', function() {
		listener.removeListener();

		if ( dataFiltered ) {
			console.log( 'Data loaded into editor "' + editor.name + '" has been filtered.' );
			// Note: Even correct, not filtered data may
			// have different length because of changes
			// in formatting. This message is therefore
			// only for demonstrative purposes.
			console.log( 'Original data length: ' + originalData.length );
			console.log( 'Filtered data length: ' + editor.getData().length );
		}
	} );
} );

The snippet can be adjusted to your needs. Please note, however, that if you are loading data in a non-standard way (namely, after instanceReady), you will need to modify it in order to take this into account.

Disabling ACF

If you are not sure whether your ACF integration works properly and are unable to check it, it is recommended to turn content filtering off by setting config.allowedContent = true.