feat($compile): expose transclusion $slots on the $transclude function

Unfilled optional slots will exist as properties of `$slots` but have a value of `null`.

Closes angular#13426

Author: petebacondarwin

src/ng/compile.js

@@ -237,7 +237,8 @@
  *          as those elements need to created and cloned in a special way when they are defined outside their
  *          usual containers (e.g. like `<svg>`).
  *        * See also the `directive.templateNamespace` property.
- *
+ *    The `$transclude` function has a property called `$slots`, which is a hash of slot names to slot transclusion
+ *    functions. If a slot was declared but not filled its value on the `$slots` object will be `null`.
  *
  * #### `require`
  * Require another directive and inject its controller as the fourth argument to the linking function. The
@@ -347,6 +348,13 @@
  * * **`{...}` (an object hash):** - map elements of the content onto transclusion "slots" in the template.
  *   See {@link ngTransclude} for more information.
  *
+ * Mult-slot transclusion is declared by providing an object for the `transclude` property.
+ * This object is a map where the keys are the canonical name of HTML elements to match in the transcluded HTML,
+ * and the values are the names of the slots. If the name is prefixed with a `?` then that slot is optional.
+ *
+ * The slots are made available as `$transclude.$slots` on the transclude function that is passed to the
+ * linking functions as the fifth parameter, and can be injected into the directive controller.
+ *
  * #### `compile`
  *
  * ```js
@@ -2137,7 +2145,8 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
           // is later passed as `parentBoundTranscludeFn` to `publicLinkFn`
           transcludeFn = controllersBoundTransclude;
           transcludeFn.$$boundTransclude = boundTranscludeFn;
-          transcludeFn.$$slots = boundTranscludeFn.$$slots;
+          // expose the slots on the `$transclude` function
+          transcludeFn.$slots = boundTranscludeFn.$$slots;
         }
 
         if (controllerDirectives) {
@@ -2234,18 +2243,22 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
             futureParentElement = hasElementTranscludeDirective ? $element.parent() : $element;
           }
           if (slotName) {
+            // slotTranscludeFn can be one of three things:
+            //  * a transclude function - a filled slot
+            //  * `null` - an optional slot that was not filled
+            //  * `undefined` - a slot that was not declared (i.e. invalid)
             var slotTranscludeFn = boundTranscludeFn.$$slots[slotName];
             if (slotTranscludeFn) {
               return slotTranscludeFn(scope, cloneAttachFn, transcludeControllers, futureParentElement, scopeToChild);
-            }
-            if (isUndefined(slotTranscludeFn)) {
+            } else if (isUndefined(slotTranscludeFn)) {
               throw $compileMinErr('noslot',
                'No parent directive that requires a transclusion with slot name "{0}". ' +
                'Element: {1}',
                slotName, startingTag($element));
             }
+          } else {
+            return boundTranscludeFn(scope, cloneAttachFn, transcludeControllers, futureParentElement, scopeToChild);
           }
-          return boundTranscludeFn(scope, cloneAttachFn, transcludeControllers, futureParentElement, scopeToChild);
         }
       }
     }

test/ng/compileSpec.js

@@ -7918,7 +7918,7 @@ describe('$compile', function() {
     });
 
 
-    it('should provide the elements marked with matching transclude elements as additional transclude functions on the $$slots property', function() {
+    it('should provide the elements marked with matching transclude elements as additional transclude functions on the $slots property', function() {
       var capturedTranscludeFn;
       module(function() {
         directive('minionComponent', function() {
@@ -7949,7 +7949,7 @@ describe('$compile', function() {
           '</minion-component>')($rootScope);
         $rootScope.$apply();
 
-        var minionTranscludeFn = capturedTranscludeFn.$$slots['minionSlot'];
+        var minionTranscludeFn = capturedTranscludeFn.$slots['minionSlot'];
         var minions = minionTranscludeFn();
         expect(minions[0].outerHTML).toEqual('<minion class="ng-scope">stuart</minion>');
         expect(minions[1].outerHTML).toEqual('<minion class="ng-scope">bob</minion>');
@@ -7959,7 +7959,7 @@ describe('$compile', function() {
         var minionScope = jqLite(minions[0]).scope();
         expect(minionScope.$parent).toBe(scope);
 
-        var bossTranscludeFn = capturedTranscludeFn.$$slots['bossSlot'];
+        var bossTranscludeFn = capturedTranscludeFn.$slots['bossSlot'];
         var boss = bossTranscludeFn();
         expect(boss[0].outerHTML).toEqual('<boss class="ng-scope">gru</boss>');
 
@@ -7973,7 +7973,7 @@ describe('$compile', function() {
       });
     });
 
-    it('should set unfilled optional transclude slots to `null` in the $transclude.$$slots property', function() {
+    it('should set unfilled optional transclude slots to `null` in the $transclude.$slots property', function() {
       var capturedTranscludeFn;
       module(function() {
         directive('minionComponent', function() {
@@ -7996,8 +7996,8 @@ describe('$compile', function() {
             '<minion>stuart</minion>' +
             '<span>dorothy</span>' +
           '</minion-component>')($rootScope);
-        expect(capturedTranscludeFn.$$slots.minionSlot).toEqual(jasmine.any(Function));
-        expect(capturedTranscludeFn.$$slots.bossSlot).toBe(null);
+        expect(capturedTranscludeFn.$slots.minionSlot).toEqual(jasmine.any(Function));
+        expect(capturedTranscludeFn.$slots.bossSlot).toBe(null);
       });
     });