feat($compile): expose publicLinkFn options

Use `options` object hash style parameter for publicLinkFn. Expose
`options` parameter as part of the public API.

Closes angular#9413

src/ng/compile.js

@@ -622,10 +622,17 @@
  *
  *
  * @param {string|DOMElement} element Element or HTML string to compile into a template function.
- * @param {function(angular.Scope, cloneAttachFn=)} transclude function available to directives.
+ * @param {function(angular.Scope, cloneAttachFn=)} transclude function available to directives - DEPRECATED.
+ *
+ * <div class="alert alert-error">
+ * **Note:** Passing a `transclude` function to the $compile function is deprecated, as it
+ * e.g. will not use the right outer scope. Please pass the transclude function as a
+ * `parentBoundTranscludeFn` to the link function instead.
+ * </div>
+ *
  * @param {number} maxPriority only apply directives lower than given priority (Only effects the
  * root element(s), not their children)
- * @returns {function(scope, cloneAttachFn=)} a link function which is used to bind template
+ * @returns {function(scope, cloneAttachFn=, options=)} a link function which is used to bind template
  * (a DOM element/tree) to a scope. Where:
  *
  * * `scope` - A {@link ng.$rootScope.Scope Scope} to bind to.
@@ -637,6 +644,19 @@
  * * `clonedElement` - is a clone of the original `element` passed into the compiler.
  * * `scope` - is the current scope with which the linking function is working with.
  *
+ * * `options` - An optional object hash with linking options. If `options` is provided, then the following
+ * keys may be used to control linking behavior:
+ *
+ * * `parentBoundTranscludeFn` - the transclude function made available to
+ * directives; if given, it will be passed through to the link functions of
+ * directives found in `element` during compilation.
+ * * `transcludeControllers` - an object hash with keys that map controller names
+ * to controller instances; if given, it will make the controllers
+ * available to directives.
+ * * `futureParentElement` - defines the parent to which the `cloneAttachFn` will add
+ * the cloned elements; only needed for transcludes that are allowed to contain non html
+ * elements (e.g. SVG elements). See also the directive.controller property.
+ *
  * Calling the linking function returns the element of the template. It is either the original
  * element passed in, or the clone of the element if the `cloneAttachFn` is provided.
  *
@@ -1155,9 +1175,14 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
  maxPriority, ignoreDirective, previousCompileContext);
  compile.$$addScopeClass($compileNodes);
  var namespace = null;
- return function publicLinkFn(scope, cloneConnectFn, transcludeControllers, parentBoundTranscludeFn, futureParentElement) {
+ return function publicLinkFn(scope, cloneConnectFn, options) {
  assertArg(scope, 'scope');
 
+ options = options || {};
+ var parentBoundTranscludeFn = options.parentBoundTranscludeFn,
+ transcludeControllers = options.transcludeControllers,
+ futureParentElement = options.futureParentElement;
+
  // When `parentBoundTranscludeFn` is passed, it is a
  // `controllersBoundTransclude` function (it was previously passed
  // as `transclude` to directive.link) so we must unwrap it to get
@@ -1335,7 +1360,11 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
  transcludedScope.$$transcluded = true;
  }
 
- return transcludeFn(transcludedScope, cloneFn, previousBoundTranscludeFn, controllers, futureParentElement);
+ return transcludeFn(transcludedScope, cloneFn, {
+ parentBoundTranscludeFn: previousBoundTranscludeFn,
+ transcludeControllers: controllers,
+ futureParentElement: futureParentElement
+ });
  };
 
  return boundTranscludeFn;

src/ng/directive/ngInclude.js

@@ -284,7 +284,7 @@ var ngIncludeFillContentDirective = ['$compile',
  $compile(jqLiteBuildFragment(ctrl.template, document).childNodes)(scope,
  function namespaceAdaptedClone(clone) {
  $element.append(clone);
- }, undefined, undefined, $element);
+ }, {futureParentElement: $element});
  return;
  }
 

test/ng/compileSpec.js

@@ -5238,7 +5238,9 @@ describe('$compile', function() {
  tElement.empty();
  return function(scope, element, attrs, ctrls, transcludeFn) {
  element.append(content);
- $compile(content)(scope, undefined, transcludeFn);
+ $compile(content)(scope, undefined, {
+ parentBoundTranscludeFn: transcludeFn
+ });
  };
  }
  };