Add callbacks (#10)

* Added a callback to be fired for each highlighted DOM node

* Fixed added callback to childnodes recursive highlight call

* Added callback to readme and formatted readme.

README.md

@@ -25,19 +25,40 @@ component install knownasilya/jquery-highlight
 
 #### $.highlight
 
-The parameters are `highlight(string|array of strings, optional options object)` and the available options are:
-
-  * `className` -- The CSS class of a highlighted element, defaults to 'highlight'.
-  * `element` -- The element that wraps the highlighted word, defaults to 'span'.
-  * `caseSensitive` -- If the search should be case sensitive, defaults to `false`.
-  * `wordsOnly` -- If we want to highlight partial sections of a word, e.g. 'ca' from 'cat', defaults to `false`.
-  * `wordsBoundary` -- If `wordsOnly` is set to `true`, this is used to determine these boundaries, defaults to `\\b` (word boundary).
-  * `wordsBoundaryStart` -- If `wordsOnly` is set to `true`, this is used to determine prefix word boundaries, defaults to the value of `wordsBoundary`.
-  * `wordsBoundaryEnd` -- If `wordsOnly` is set to `true`, this is used to determine suffix word boundaries, defaults to the value of `wordsBoundary`.
+Function signature: `highlight(word, options, callback)`
+
+The parameters are:
+
+  **word** `string|array` (required)
+
+  string such as `"lorem"` or `"lorem ipsum"` or an array of string such as `["lorem", "ipsum"]` 
+
+  **options** `object` (optional)
+
+  object with the following available options
+
+    * `className` -- The CSS class of a highlighted element, defaults to 'highlight'.
+    * `element` -- The element that wraps the highlighted word, defaults to 'span'.
+    * `caseSensitive` -- If the search should be case sensitive, defaults to `false`.
+    * `wordsOnly` -- If we want to highlight partial sections of a word, e.g. 'ca' from 'cat', defaults to `false`.
+    * `wordsBoundary` -- If `wordsOnly` is set to `true`, this is used to determine these boundaries, defaults to `\\b` (word boundary).
+    * `wordsBoundaryStart` -- If `wordsOnly` is set to `true`, this is used to determine prefix word boundaries, defaults to the value of `wordsBoundary`.
+    * `wordsBoundaryEnd` -- If `wordsOnly` is set to `true`, this is used to determine suffix word boundaries, defaults to the value of `wordsBoundary`.
+
+  **callback** `function` (optional)
+
+  function that will be called for each DOM node/element highlighted
+
 
 #### $.unhighlight
 
-The parameters are `unhighlight(optional options object)`, and the available options are:
+Function signature: `unhighlight(options)`:
+
+The parameters are:
+
+**options** `object` (optional)
+
+  object with the following available options
 
   * `className`  -- The highlights to remove based on CSS class, defaults to 'highlight'.
   * `element` -- The highlights to remove based on HTML element, defaults to 'span'.
@@ -56,6 +77,13 @@ $('#content').highlight('lorem');
 $('#content').highlight(['lorem', 'ipsum']);
 $('#content').highlight('lorem ipsum');
 
+// wrap every occurrence of text 'lorem' in content
+// with <span class='highlight'> (default options)
+// log every word highlighted to the console using the invoked callback
+$('#content').highlight('lorem', {}, function(el) {
+ console.log('highligting DOM element', el)
+});
+
 // search only for entire word 'lorem'
 $('#content').highlight('lorem', {
   wordsOnly: true

jquery.highlight.js

@@ -61,7 +61,7 @@
     }
 }(function (jQuery) {
     jQuery.extend({
-        highlight: function (node, re, nodeName, className) {
+        highlight: function (node, re, nodeName, className, callback) {
             if (node.nodeType === 3) {
                 var match = node.data.match(re);
                 if (match) {
@@ -80,13 +80,16 @@
                     var wordClone = wordNode.cloneNode(true);
                     highlight.appendChild(wordClone);
                     wordNode.parentNode.replaceChild(highlight, wordNode);
+                    if (typeof callback == 'function') {
+                        callback(highlight)   
+                    }
                     return 1; //skip added node in parent
                 }
             } else if ((node.nodeType === 1 && node.childNodes) && // only element nodes that have children
                     !/(script|style)/i.test(node.tagName) && // ignore script and style nodes
                     !(node.tagName === nodeName.toUpperCase() && node.className === className)) { // skip if already highlighted
                 for (var i = 0; i < node.childNodes.length; i++) {
-                    i += jQuery.highlight(node.childNodes[i], re, nodeName, className);
+                    i += jQuery.highlight(node.childNodes[i], re, nodeName, className, callback);
                 }
             }
             return 0;
@@ -108,7 +111,7 @@
         }).end();
     };
 
-    jQuery.fn.highlight = function (words, options) {
+    jQuery.fn.highlight = function (words, options, callback) {
         var settings = {
           className: 'highlight',
           element: 'span',
@@ -146,7 +149,7 @@
         var re = new RegExp(pattern, flag);
 
         return this.each(function () {
-            jQuery.highlight(this, re, settings.element, settings.className);
+            jQuery.highlight(this, re, settings.element, settings.className, callback);
         });
     };
 }));