Generic Content Handler

build/ctct-generic-content-handler-changelog.md

@@ -0,0 +1,4 @@
+- **ENHANCEMENT**: Enhances the generic content handler removeComments function to remove comments that appear
+                   as text nodes in Firefox.  This change also refactors the code in the generic content handler to
+                   be configuration driven.  Each sub-handler run by this content handler can be enabled or disabled
+                   via the Aloha.settings.contentHandler.handler.generic configuration.

doc/guides/source/plugin_contenthandler.textile

@@ -88,12 +88,12 @@ h4. Writing your own Content Handler
 	['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
 			}
 		});
@@ -157,6 +157,21 @@ The Generic Content Handler is a bit less generic than his name might suggest as
 ** +<s>+ and +<strike>+ to +<del>+
 ** and by removing +<u>+ tags (as underline text decoration should solely be used for links)
 
+You may specify which of the above cleaning actions will e run bgy supplying your own configuration based on these default settings:
+
+<javascript>
+Aloha.settings.contentHandler.generic = {
+  prepareTableContents: true,
+  cleanLists: true,
+  removeComments: true,
+  unwrapTags: true,
+  removeStyles: true,
+  removeNamespacedElements: true,
+  transformFormattings: true,
+  transformLinks: false
+}
+</javascript>
+
 h4. Sanitize Content Handler
 
 WARNING: The Sanitize Content Handler does not work reliably on IE7, and will therefore just do nothing, if this browser is detected.

src/plugins/common/contenthandler/lib/genericcontenthandler.js

@@ -29,128 +29,156 @@ define([
 	'aloha',
 	'aloha/contenthandlermanager',
 	'contenthandler/contenthandler-utils'
-], function (
-	$,
-	Aloha,
-	Manager,
-	Utils
-) {
+], function ($, Aloha, Manager, Utils ) {
 	'use strict';
 
-	/**
-	 * Tags used for semantic formatting
-	 * @type {Array.<String>}
-	 * @see GenericContentHandler#transformFormattings
-	 */
-	var formattingTags = ['strong', 'em', 's', 'u', 'strike'];
-
-	/**
-	 * Checks whether the markup describes a paragraph that is propped by
-	 * a <br> tag but is otherwise empty.
-	 * 
-	 * Will return true for:
-	 *
-	 * <p id="foo"><br class="bar" /></p>
-	 *
-	 * as well as:
-	 *
-	 * <p><br></p>
-	 *
-	 * @param {string} html Markup
-	 * @return {boolean} True if html describes a propped paragraph.
-	 */
-	function isProppedParagraph(html) {
-		var trimmed = $.trim(html);
-		if (!trimmed) {
-			return false;
-		}
-		var node = $('<div>' + trimmed + '</div>')[0];
-		var containsSingleP = node.firstChild === node.lastChild
-		    && 'p' === node.firstChild.nodeName.toLowerCase();
-		if (containsSingleP) {
-			var kids = node.firstChild.children;
-			return (kids && 1 === kids.length &&
-					'br' === kids[0].nodeName.toLowerCase());
-		}
-		return false;
-	}
-
-
-	/**
-	 * Transforms all tables in the given content to make them ready to for
-	 * use with Aloha's table handling.
-	 *
-	 * Cleans tables of their unwanted attributes.
-	 * Normalizes table cells.
-	 *
-	 * @param {jQuery.<HTMLElement>} $content
-	 */
-	function prepareTables($content) {
-		// Because Aloha does not provide a way for the editor to
-		// manipulate borders, cellspacing, cellpadding in tables.
-		// @todo what about width, height?
-		$content.find('table')
-			.removeAttr('cellpadding')
-			.removeAttr('cellspacing')
-			.removeAttr('border')
-			.removeAttr('border-top')
-			.removeAttr('border-bottom')
-			.removeAttr('border-left')
-			.removeAttr('border-right');
-
-		$content.find('td').each(function () {
-			var td = this;
-
-			// Because cells with a single empty <p> are rendered to appear
-			// like empty cells, it simplifies the handeling of cells to
-			// normalize these table cells to contain actual white space
-			// instead.
-			if (isProppedParagraph(td.innerHTML)) {
-				td.innerHTML = '&nbsp;';
-			}
-
-			// Because a single <p> wrapping the contents of a <td> is
-			// initially superfluous and should be stripped out.
-			var $p = $('>p', td);
-			if (1 === $p.length) {
-				$p.contents().unwrap();
-			}
-		});
-
-		// Because Aloha does not provide a means for editors to manipulate
-		// these properties.
-		$content.find('table,th,td,tr')
-			.removeAttr('width')
-			.removeAttr('height')
-			.removeAttr('valign');
-
-		// Because Aloha table handling simply does not regard colgroups.
-		// @TODO Use sanitize.js?
-		$content.find('colgroup').remove();
-	}
-
-	/**
-	 * Return true if the nodeType is allowed in the settings,
-	 * Aloha.settings.contentHandler.allows.elements
-	 * 
-	 * @param {String} nodeType	The tag name of the element to evaluate
-	 * 
-	 * @return {Boolean}
-	 */
-	function isAllowedNodeName(nodeType){
-		return !!(
-			Aloha.settings.contentHandler
-			&& Aloha.settings.contentHandler.allows
-			&& Aloha.settings.contentHandler.allows.elements
-			&& ($.inArray(
-		              nodeType.toLowerCase(), 
-				      Aloha.settings.contentHandler.allows.elements
-				         ) !== -1
-			   )
-		);
-	}
-
-	var GenericContentHandler = Manager.createHandler({
+    var defaultConfig = {
+        handlers: {
+            prepareTableContents: true,
+            cleanLists: true,
+            removeComments: true,
+            unwrapTags: true,
+            removeStyles: true,
+            removeNamespacedElements: true,
+            transformFormattings: true,
+            transformLinks: false
+        }
+    };
+
+    var handlers = (function() {
+        var config = {};
+        var init = function() {
+            if (Aloha.settings.contentHandler
+                && Aloha.settings.contentHandler.handler
+                && Aloha.settings.contentHandler.handler.generic) {
+                config = jQuery.extend({}, defaultConfig.handlers, Aloha.settings.contentHandler.handler.generic);
+            } else {
+                config = defaultConfig.handlers;
+            }
+        };
+
+        return {
+            config: function() {
+                init();
+                return config;
+            }
+        };
+    })();
+
+    /**
+    * Tags used for semantic formatting
+    * @type {Array.<String>}
+    * @see GenericContentHandler#transformFormattings
+    */
+    var formattingTags = ['strong', 'em', 's', 'u', 'strike'];
+
+    /**
+    * Checks whether the markup describes a paragraph that is propped by
+    * a <br> tag but is otherwise empty.
+    *
+    * Will return true for:
+    *
+    * <p id="foo"><br class="bar" /></p>
+    *
+    * as well as:
+    *
+    * <p><br></p>
+    *
+    * @param {string} html Markup
+    * @return {boolean} True if html describes a propped paragraph.
+    */
+    function isProppedParagraph(html) {
+    var trimmed = $.trim(html);
+    if (!trimmed) {
+      return false;
+    }
+    var node = $('<div>' + trimmed + '</div>')[0];
+    var containsSingleP = node.firstChild === node.lastChild
+        && 'p' === node.firstChild.nodeName.toLowerCase();
+    if (containsSingleP) {
+      var kids = node.firstChild.children;
+      return (kids && 1 === kids.length &&
+          'br' === kids[0].nodeName.toLowerCase());
+    }
+    return false;
+    }
+
+
+    /**
+    * Transforms all tables in the given content to make them ready to for
+    * use with Aloha's table handling.
+    *
+    * Cleans tables of their unwanted attributes.
+    * Normalizes table cells.
+    *
+    * @param {jQuery.<HTMLElement>} $content
+    */
+    function prepareTables($content) {
+    // Because Aloha does not provide a way for the editor to
+    // manipulate borders, cellspacing, cellpadding in tables.
+    // @todo what about width, height?
+    $content.find('table')
+      .removeAttr('cellpadding')
+      .removeAttr('cellspacing')
+      .removeAttr('border')
+      .removeAttr('border-top')
+      .removeAttr('border-bottom')
+      .removeAttr('border-left')
+      .removeAttr('border-right');
+
+    $content.find('td').each(function () {
+      var td = this;
+
+      // Because cells with a single empty <p> are rendered to appear
+      // like empty cells, it simplifies the handeling of cells to
+      // normalize these table cells to contain actual white space
+      // instead.
+      if (isProppedParagraph(td.innerHTML)) {
+        td.innerHTML = '&nbsp;';
+      }
+
+      // Because a single <p> wrapping the contents of a <td> is
+      // initially superfluous and should be stripped out.
+      var $p = $('>p', td);
+      if (1 === $p.length) {
+        $p.contents().unwrap();
+      }
+    });
+
+    // Because Aloha does not provide a means for editors to manipulate
+    // these properties.
+    $content.find('table,th,td,tr')
+      .removeAttr('width')
+      .removeAttr('height')
+      .removeAttr('valign');
+
+    // Because Aloha table handling simply does not regard colgroups.
+    // @TODO Use sanitize.js?
+    $content.find('colgroup').remove();
+    }
+
+    /**
+    * Return true if the nodeType is allowed in the settings,
+    * Aloha.settings.contentHandler.allows.elements
+    *
+    * @param {String} nodeType	The tag name of the element to evaluate
+    *
+    * @return {Boolean}
+    */
+    function isAllowedNodeName(nodeType){
+    return !!(
+      Aloha.settings.contentHandler
+      && Aloha.settings.contentHandler.allows
+      && Aloha.settings.contentHandler.allows.elements
+      && ($.inArray(
+                  nodeType.toLowerCase(),
+              Aloha.settings.contentHandler.allows.elements
+                 ) !== -1
+         )
+    );
+    }
+
+	  var GenericContentHandler = Manager.createHandler({
 
 		/**
 		 * Transforms pasted content to make it safe and ready to be used in
@@ -173,31 +201,25 @@ define([
 				return $content.html();
 			}
 
-			prepareTables($content);
-			this.cleanLists($content);
-			this.removeComments($content);
-			this.unwrapTags($content);
-			this.removeStyles($content);
-			this.removeNamespacedElements($content);
-			//this.transformLinks($content);
-
-			var transformFormatting = true;
-
-			if (Aloha.settings.contentHandler
-				&& Aloha.settings.contentHandler.handler
-				&& Aloha.settings.contentHandler.handler.generic
-				&& typeof Aloha.settings.contentHandler.handler.generic.transformFormattings !== 'undefinded'
-				&& !Aloha.settings.contentHandler.handler.generic.transformFormattings ) {
-				transformFormatting = false;
-			}
-
-			if (transformFormatting) {
-			    this.transformFormattings($content);
-			}
+            // Run each configured handler.
+            var handler, config = handlers.config();
+            for (handler in config) {
+                if (config[handler]) {
+                    this[handler]($content);
+                }
+            }
 
 			return $content.html();
 		},
 
+    /**
+     * Prepares table contents
+     * @param $content
+     */
+    prepareTableContents: function($content) {
+        prepareTables($content);
+    },
+
 		/**
 		 * Cleans lists.
 		 * The only allowed children of ol or ul elements are li's. Everything
@@ -274,6 +296,9 @@ define([
 			content.contents().each(function () {
 				if (this.nodeType === 8) {
 					$(this).remove();
+                } else if (this.nodeType == 3) {
+                    // In FF, comments appear as text nodes
+                    this.textContent = this.textContent.replace(/<!--[\s\S]*?-->/g, '');
 				} else {
 					// do recursion
 					that.removeComments($(this));