First commit

Author: Mark Lagendijk

README.md

@@ -1,4 +1,33 @@
-angular-recursion-helper
-========================
+# angular-recursion-helper
 
 A service which makes it easy possible to have recursive Angular directives.
+
+## Why
+When an Angular directive calls itself, Angular gets into an endless loop. This service provides the logic needed to work around this.
+
+## Usage
+The service is used by injecting it into your directive and using it in the directives' compile function. The following example shows this. See [this fiddle](http://jsfiddle.net/xUsCc/34/) to see this example running.
+
+``` javascript
+module.directive("tree", function(RecursionHelper) {
+    return {
+        restrict: "E",
+        scope: {family: '='},
+        template: 
+        '<p>{{ family.name }}{{test }}</p>'+
+            '<ul>' + 
+                '<li ng-repeat="child in family.children">' + 
+                    '<tree family="child"></tree>' +
+                '</li>' +
+            '</ul>',
+        compile: function(element) {
+            return RecursionHelper.compile(element, function(scope, iElement, iAttrs, controller, transcludeFn){
+                // Define your normal link function here.
+                // Alternative: instead of passing a function,
+                // you can also pass an object with 
+                // a 'pre'- and 'post'-link function.
+            });
+        }
+    };
+});
+```

recursionhelper.js

@@ -0,0 +1,41 @@
+module.factory('RecursionHelper', ['$compile', function($compile){
+	return {
+		/**
+		 * Manually compiles the element, fixing the recursion loop.
+		 * @param element
+		 * @param [link] A post-link function, or an object with function(s) registered via pre and post properties.
+		 * @returns An object containing the linking functions.
+		 */
+		compile: function(element, link){
+			// Normalize the link parameter
+			if(angular.isFunction(link)){
+				link = { post: link };
+			}
+
+			// Break the recursion loop by removing the contents
+			var contents = element.contents().remove();
+			var compiledContents;
+			return {
+				pre: (link && link.pre) ? link.pre : null,
+				/**
+				 * Compiles and re-adds the contents
+				 */
+				post: function(scope, element){
+					// Compile the contents
+					if(!compiledContents){
+						compiledContents = $compile(contents);
+					}
+					// Re-add the compiled contents to the element
+					compiledContents(scope, function(clone){
+						element.append(clone);
+					});
+
+					// Call the post-linking function, if any
+					if(link && link.post){
+						link.post.apply(null, arguments);
+					}
+				}
+			};
+		}
+	};
+}]);