Aloha Editor

Aloha Guides

These guides help you to make your content editable and to develop Aloha.

The Content Handler Plugin

After reading this guide, you will be able to:

  • Understand what Content Handler are and how to use them
  • Use the Content Handler API to create, modify and
  • Extend Content Handler with custom implementations

This guide is currently work-in-progress.

1 What are Content Handler?

Aloha Content Handler (Content Handler) are used to sanitize content loaded or pasted in Aloha Editor.

There are some Content Handler available:

  • Generic
  • Word
  • oEmbed
  • Sanitize

Plugins also provide Content Handler:

  • Block common/block plugin

There are two hocks available:

  • insertHtml in common/commands plugin
  • initEditable in core/editable.js

2 Enabling the Content Handler Plugin

2.1 Using Configuration


	Aloha.settings.contentHandler: {
		insertHtml: [ 'word', 'generic', 'oembed', 'sanitize' ],
		initEditable: [ 'sanitize' ],
		sanitize: 'relaxed' // relaxed, restricted, basic,
		allows: {
			elements: [
				'strong', 'em', 'i', 'b', 'blockquote', 'br', 'cite', 'code', 'dd', 'div', 'dl', 'dt', 'em',
				'i', 'li', 'ol', 'p', 'pre', 'q', 'small', 'strike', 'sub',
				'sup', 'u', 'ul'],

			attributes: {
				'a'         : ['href'],
				'blockquote': ['cite'],
				'q'         : ['cite']
			 },

			protocols: {
				'a'         : {'href': ['ftp', 'http', 'https', 'mailto', '__relative__']}, // Sanitize.RELATIVE
				'blockquote': {'cite': ['http', 'https', '__relative__']},
				'q'         : {'cite': ['http', 'https', '__relative__']}
			}
		}
	}

For the sanitize Content Handler you can use a predefined set of allowed HTML-tags and attributes (“sanitize” option) or your own set defined as “allows” option. The configuration option for “insertHtml” and “initEditable” defines which Content Handler should be used at that hook points. “initEditable” uses the “sanitize” Content Handler by default. “insertHtml” uses all registered Content Handler by default (including the Content Handler from other Plugins)

The order how the handlers are loaded and executed is important. If you first load the “sanitize” or “generic” handler the “word” handler will not be able to detect a MS Word document.

3 APIs and Extension Points

There is the Content Handler Manager in Aloha Core available where Content Handler can register themself.

3.1 Writing your own Content Handler


	define(
	['aloha', 'aloha/jquery', 'aloha/contenthandlermanager'],
	function(Aloha, jQuery, ContentHandlerManager) {
		"use strict";
	
		var MyContentHandler = ContentHandlerManager.createHandler({
			handleContent: function( content ) {
				
				// do something with the content
				
				return content; // return as HTML text not jQuery/DOM object
			}
		});

		return MyContentHandler;
	});

All Content Handler needs to support the “handleContent” method and will receive and return the content as HTML text.

4 Internals

5 Future Work

6 Changelog