Put the knife down and take a green herb, dude. (c) Ruffin Bailey 2001-2021

Any time I forget something more than once, I should probably blog about it. Saves me time looking for a comment on SO I put on an answer I particularly appreciated.

Because I've forgotten this particular something more than once, let's return to our time machine, travel back to AngularJS land again, and leave some notes.

What's an "ampersand binding" in AngularJS?

Essentially, an ampersand binding allows you to mark that you're passing an event handler function to a custom component.

Here's one mention in the AngularJS docs:

We saw earlier how to use =attr in the scope option, but in the above example, we're using &attr instead. The & binding allows a directive to trigger evaluation of an expression in the context of the original scope, at a specific time. Any legal expression is allowed, including an expression which contains a function call. Because of this, & bindings are ideal for binding callback functions to directive behaviors.

(There may be a better reference in the docs, but man it's hard to google an ampersand. They could have also ensured something that made it easier to find, like if it had a clear name similar to "ampersand component binding", but the AngularJS folk weren't nice enough to do that either afacit.)

Here's some example code [of mine :shudder:] that uses it:

angular.module('app').component('qbTristateCheckbox', {
    template:
        '<input ' +
        'ng-class="tsc.classes" ' +
        'ng-disabled="tsc.isDisabled()" ' +
        'ng-click="tsc.wasChecked($event)" ' +
        'ng-attr-id="{{tsc.checkboxId}}" ' +
        'type="checkbox" />',
        
    controller: QbTristateCheckboxController,
    controllerAs: 'tsc',
    
    bindings: {
        labelDisplay: '@',

        checkState: '<',
        checkboxClasses: '<',
        ngDisabled: '<',
        checkboxId: '<',

        clickHandler: '&', // <<< THIS ONE IS WHAT WE'RE TALKING ABOUT
    },
});

In this case, we've got a custom checkbox component that supports tristate. Specifically, that means it's a wrapper that enables easy access to checked, unchecked, and indeterminate states (three states, not the usual two. Am I over explaining this? ;^D) in an html form checkbox input.

Indeterminate status checkboxes are kinda complicated in vanilla HTML, and this is trying to abstract some of that in a package AngularJS can consume easily.

As a freakin' huge proponent of props down, events up, the tristate checkbox is a very black box.

You tell it the state it should be in by passing down the value carried by the prop checkState (here, for simplicity's sake, 0, 1, or 3 [sic]).
When it's clicked, it tells you that's happened by calling the event handler contained in clickHandler.

checkState down. clickHandler up.

Where the ampersand binding bites you

The problem is that the ampersand binding doesn't give a function for your component's controller that you can call in a conventional sense.

If clickHandler's signature on the tristate checkbox component's parent looks like this...

vm.checkHandler = function (permission, permissionType, newCheckState) {

... you'd never guess how you pass newCheckState from the child custom component to the function.

Here's an example (again, this is a real-world example. It's a little more use case specific than I'd like for a perfect demo):

<qb-tristate-checkbox
    ng-disabled="!qpc.canAssign(permission, 'Write')"
    checkbox-id="'write-' + index"
    check-state="permission.Write"

    label-display="''"

    click-handler="qpc.checkHandler(permission, 'Write', newCheckState)"
></qb-tristate-checkbox>

permission is from an ng-repeat parent tag:

<li
    class="instructorPermissions text-center list-group-item row no-gutters justify-content-between"
    ng-if="qpc.questionIds && qpc.questionIds.length"
    
    ng-repeat="(index, permission) in qpc.processedPermissions | orderBy: ['-Owner','UserName']"
>
<!--                   ^^^^^^^^^^ that permission right there -->

'Write' is obviously just a static string.

But newCheckState comes from the component. It's the only value coming from the tristate checkbox that we care about.

How do I pass it?

Like this:

vm.clickHandler({
    newCheckState: value,
});

Inside of an object literal? Wait, WTFOMGBBQNSFW!!!!!

At first, I would've expected the event handler registration in the template to look like this:

<qb-tristate-checkbox
    click-handler="qpc.checkHandler" <<< Purely passing a reference
></qb-tristate-checkbox>

... and the call from within the component to look like this...

// again, this would be within the QbTristateCheckboxController
vm.clickHandler(permission, 'Write', value)

But it's not.

I would have also accepted something in the component that lets you know you're calling a weirdly wrapped event handler prop, something like...

vm.callAmpersandBinding('clickHandler', permission, 'Write', value);

That's funky, but it has the benefit of letting you know something funky is going on. I mean, if clickHandler is a prop, and it has a function assigned to it, calling that reference should call the literal function, right?

Um, no. No. Not at all. Instead, we have to pass that value by embedding in an object literal. In fact, if we wanted to pass all three from the component, the code would look like...

<!-- template -->
<qb-tristate-checkbox
    click-handler="qpc.checkHandler(permission, staticString, newCheckState)"
></qb-tristate-checkbox>

and

vm.clickHandler({
    newCheckState: value,
    permission: vm.processedPermisions[someMagicIndex], // <<< How do I find this?
    staticString: 'Write' // Outside of the template, neither makes sense
});

Instead of letting us call the handler directly, AngularJS provides some weird monkeypatching that makes clickHandler in our controller call a wrapped version of the event handler.

The advantages of the AngularJS ampersand binding convention

It's not all bad. What's neat about this is that it does allow us to combine jive from the template scope, like our permission from the ng-repeat, into an event handler call with variables sent from the component.

a visual representation of the relationship of the template, component parent, and component scopes to the event handler call

That is, by not limiting the call to the event handler from within the component to the literal event handler signature, we've got a lot more flexibility. We can combine two scopes, custom component controller and template contexts.

At the same time, though passing an object literal that maps to parameters named only in a prop definition in a template file might be more flexible, it's an extremely unintuitive, indiscoverable convention.

That we were establishing a new convention and why really didn't click for me until I understood how the new convention was useful -- precisely so that we could mix parent template and component controller scopes like this.

Put another way...

If that didn't click, here's a good explanation from superluminary on SO of the [unintuitive] way an ampersand binding in AngularJS works, and is what finally made how things worked click in my head. Once I had this convention straight and was able to combine it with the advantages of in-template parameter mixing, I was finally an ampersand binding expert. (Until I forgot.)

Anyhow, from that answer:

TL;DR; - You are assuming that the bound function is being passed to the child component. This is incorrect. In fact, AngularJS is parsing the string template and creating a new function, which then calls the parent function.
This function needs to receive an object with keys and values, rather than a plain variable. _{[emphasis mine -mfn]}

...

Say I create a component like this:
const MyComponent = {
  bindings: {
    onSearch: '&'
  },
  controller: controller
};
This function (in the parent) looks like this:
onSearch(value) {
  // do search
}
In my parent template, I can now do this:
<my-component on-search="onSearch(value)"></my-component>
...

In myComponent controller, I need to do something like:
handleOnSearch(value) {
  if (this.onSearch) {
    this.onSearch({value: value})
  }
}

It's almost like AngularJS said, "I see your event handler, and I'm going to raise you this monkeypatch..."

componentController.clickHandler = function(paramsAsObjectLiteral) {
    parentScope.clickHandler({
        paramsAsObjectLiteral['newCheckState'] || templateContext.newCheckState,
        paramsAsObjectLiteral['staticString'] || templateContext.staticString,
        paramsAsObjectLiteral['permission'] || templateContext.permission,
    });
};

(Actually, that's functionally speaking exactly what AngularJS does, though there's another round of mapping after you compiled the template to code before you can have templateContext and I'm not sure which, the component or template's version of variables, really takes precedence (which goes on the left side of the ||s). The template would make more sense, I guess.)

What people usually end up doing... and why you shouldn't

The weird part is that you can skip this new convention entirely if you pass the event handler by reference. It's cheating, I'm pretty sure the AngularJS wishes you wouldn't, and you lose a lot of flexibility, but I can see why people do it. The ampersand binding convention simply isn't easily intuitive.

Here's one such example of that "my mind is blown; gimme simple" mentality from krawaller.se:

Because & is so convoluted, many use = to do output [...but...] A nicer solution than all of the above is to use < to create output by passing in a callback!
We create the callback in the outer controller...
$scope.callback = function(amount){
  $scope.count += amount;
}
...and pass it to the component:
<output out="callback"></output>
The component now simply calls it accordingly:
app.component("output",{
  bindings: { out: '<' },
  template: `
    <button ng-click="$ctrl.out(1)">buy one</button>
    <button ng-click="$ctrl.out(5)">buy many</button>`
});
Very similar to &, but without the convoluted magic!

Then, in your controller, you'd simply call vm.out(myAmount) somewhere, where myAmount is a variable inside of your custom child component's scope.

But recall that you now can't do anything clever with your template's scope! As long as the template is something trivial like the <output out="callback"></output> we have here, fine, sure, you're golden. But as soon as you're one ng-repeat in, you're going to want to brush off that &.

Anyhow, I've known the ampersand binding convention long enough to use it and forget it once already, so there's a refresher. Hope that's helpful if you too have been sucked INTO AN ANACHRONISTIC ANGULARJS TIME BOB OMB!!!!1!!!

Labels: angularjs, noteToSelf

// a silly directive to repeat the items of a dictionary object. app.directive('keyValueRepeat', function ($compile){ return { transclude: true, scope: { data: '=', showDebug: '@' }, compile: function(elem, attrs, transclude) { if(attrs.showDebug) { elem.append('<div class="debug">DEBUG ENABLED {{showDebug}}</div>'); } return function(scope, lElem, lAttrs) { var items = []; console.log(lElem); scope.$watch('data', function(data) { // remove old values from the tracking array // (see below) for(var i = items.length; i-- > 0;) { items[i].element.remove(); items[i].scope.$destroy(); items.splice(i,1); } //add new ones for(var key in data) { var val = data[key], childScope = scope.$new(), childElement = angular.element('<div></div>'); // for each item in our repeater, we're going to create it's // own scope and set the key and value properties on it. childScope.key = key; childScope.value = val; // do the transclusion. transclude(childScope, function(clone, innerScope) { //clone is a copy of the transcluded DOM element content. console.log(clone); // Because we're still inside the compile function of the directive, // we can alter the contents of each output item // based on an attribute passed. if(attrs.showDebug) { clone.prepend('<span class="debug">{{key}}: {{value}}</span>'); } //append the transcluded element. childElement.append($compile(clone)(innerScope)); }); // add the objects made to a tracking array. // so we can remove them later when we need to update. items.push({ element: childElement, scope: childScope }); lElem.append(childElement); } }); }; } }; });

scope.control.openModal = function () { scope.instance = $uibModal.open({ animation: false, scope: scope, template: '<div>in the template</div><div class="content"></div>', appendTo: element }); /** * Give Angular some time to render your DOM */ $timeout(function (){ /** * Since you have jQuery loaded already */ var content = element.find('.content'); /** * Finally, append the transcluded element to the correct position, * while also making sure that the cloned DOM is bound to the parent scope (i.e. ctl) */ transclude(scope.$parent, function(clonedContent){ content.append(clonedContent); }); }); };

<div id="multiMessageModal" class="modal-body"> <span ng-repeat="message in messages">  <p ng-if="message.text">{{message.text}}</p>  <ul ng-if="isArray(message.listItems) && message.listItems.length"> <li ng-repeat="listitem in message.listItems">{{listitem}}</li> </ul>  </span> </div>

.component('mySelect', { bind: { collection: '<', }, transclude: { header: '?header', // note the `?` to keep each one optional body: '?body', // also note that you can change the names footer: '?footer', // between parent element and component template. }, templateUrl: '/path/to/your/template.html', });

<script type="text/ng-template" id="myModalContent.html"> <div class="modal-header" ng-transclude="header"> <h3 class="modal-title" id="modal-title">I'm a modal!</h3> </div> <div class="modal-body" id="modal-body" ng-transclude="body"></div> <div class="modal-footer" ng-transclude="footer"> <button class="btn btn-primary" type="button" ng-click="$ctrl.ok()">OK</button> <button class="btn btn-warning" type="button" ng-click="$ctrl.cancel()">Cancel</button> </div> </script>

app.directive("theModal", function($uibModal) { return { restrict: "AE", scope: { control: "=" }, transclude: true, link: function (scope, element, attrs, ctrl, transclude) {// <<<<<< This and... scope.control = scope.control || {} scope.control.openModal = function () { scope.instance = $uibModal.open({ animation: false, scope: scope, template: '<div>in the template</div><div class="content"></div>' }); element.find('.content').append(transclude()); // <<<<<< ... this look promising. (-mfn) }; } } });

<div class="modal-body"> <span ng-repeat="message in messages"> <p ng-if="message.text">{{message.text}}</p> <ul ng-if="isArray(message.listItems) && message.listItems.length"> <li ng-repeat="listitem in message.listItems">{{listitem}}</li> </ul> </span> </div>

Here's Today Adventure in Enjoyable AngularJS...

I ran into some code from a project that looked give or take like this...

namespace.directive('caNavigation', function () { "use strict"; return { restrict: 'E', scope: { inLinks: "@", collapseNav: "=" }, // ... controller: ["$scope", /* more jive */], function ($scope /* more jive */) { $scope.$watch('inLinks', function (value) { // omgwtfbbq? // ...
Well, that's @ and = stuff is pretty cryptic, especially since I hadn't used a directive in AngularJS before (Angular 2+, sure, but still learning ye olde AngularJS -- going backwards, I know. Don't forget I had my first run-in with Perl in 2014 [sic]).

Let's see what ye olde docs say:

[Having to have a separate controller to change direct scopes] is clearly not a great solution.

What we want to be able to do is separate the scope inside a directive from the scope outside, and then map the outer scope to a directive's inner scope. We can do this by creating what we call an isolate scope. To do this, we can use a directive's scope option:

...

Let's take a closer look at the scope option:
//...
scope: {
customerInfo: '=info'
},
//...
The scope option is an object that contains a property for each isolate scope binding. In this case it has just one property:

Its name (customerInfo) corresponds to the directive's isolate scope property, customerInfo.

Its value (=info) tells $compile to bind to the info attribute.

Good heavens, AngularJS. Not the most discoverable. Seems like in AngularJS in general there's lots of magic stringing. Perhaps I shouldn't be surprised, but that doesn't mean I like it. (Here I mean largely inline array notation, which is too hipster by half. I mean, I get that you don't what to lose information when you minimize, but then how about pass real references, not refer to objects by their original names? Sheesh.* )

But let's go a little deeper so that we know what the @ symbol means too.

The 'isolate' scope object hash defines a set of local scope properties derived from attributes on the directive's element. These local properties are useful for aliasing values for templates. The keys in the object hash map to the name of the property on the isolate scope; the values define how the property is bound to the parent scope, via matching attributes on the directive's element:

@ or @attr - bind a local scope property to the value of DOM attribute. The result is always a string since DOM attributes are strings. If no attr name is specified then the attribute name is assumed to be the same as the local name. Given <my-component my-attr="hello {{name}}"> and the isolate scope definition scope: { localName:'@myAttr' }, the directive's scope property localName will reflect the interpolated value of hello {{name}}. As the name attribute changes so will the localName property on the directive's scope. The name is read from the parent scope (not the directive's scope).

= or =attr - set up a bidirectional binding between a local scope property and an expression passed via the attribute attr. The expression is evaluated in the context of the parent scope. If no attr name is specified then the attribute name is assumed to be the same as the local name. Given <my-component my-attr="parentModel"> and the isolate scope definition scope: { localModel: '=myAttr' }, the property localModel on the directive's scope will reflect the value of parentModel on the parent scope. Changes to parentModel will be reflected in localModel and vice versa. If the binding expression is non-assignable, or if the attribute isn't optional and doesn't exist, an exception ($compile:nonassign) will be thrown upon discovering changes to the local value, since it will be impossible to sync them back to the parent scope.

By default, the $watch method is used for tracking changes, and the equality check is based on object identity. However, if an object literal or an array literal is passed as the binding expression, the equality check is done by value (using the angular.equals function). It's also possible to watch the evaluated value shallowly with $watchCollection: use =* or =*attr

If you've used Angular 2+ (what a failed naming scheme, btw. Why not "Angular.IO" after the website or just NGular or something so that googling this jive would be easier?), you can already see our steady progression to banana boxes.

But for now, what a mess.

If a scope property is a string that starts with @, then we'll initialize that scope property with the directive's DOM attribute that matches what comes after the @.

That is, this is a one-way process. Props down, and set up events if changes need to go back up.

If the prop starts with an =, we're doing the equivalent of Angular.IO's banana boxing, it appears.

So if we change whatever's in here, the parent is changing too.

Back to our original example now... We had a cryptic (to me) $scope.$watch('inLinks', function (value)..., and now we know what that means. @ means we've got a prop that $watch can check for changes, which, in this case, means:

The listener is called only when the value from the current watchExpression and the previous call to watchExpression are not equal (with the exception of the initial run, see below). Inequality is determined according to reference inequality, strict comparison via the !== Javascript operator, unless objectEquality == true (see next point)

When objectEquality == true, inequality of the watchExpression is determined according to the angular.equals function. To save the value of the object for later comparison, the angular.copy function is used. This therefore means that watching complex objects will have adverse memory and performance implications.

Guess that works. Let's ignore the =* shallow comparison jive for now. All we've really got is one prop called inLinks that will be passed... um... "in" that we'll update whenever it changes, probably after the page finishes loading and making some resource calls. And sure enough...

<li ng-repeat="subLink in link.SubLinks|filter: {ShowInNav: true}" ...
That means once we've loaded the correct navigational links for this context, we'll start pushing them into the DOM.

And our code makes sense. Much rejoicing.

* I actually kinda like AngularJS. It's one clean step away from the inefficient, overly-engineered land of enterprise development Bjarnason discusses and that at least the social convention surrounding Angular 2+ seems to require. But there are a few stupid* conventions like this one that really do AngularJS in conceptually.

* Sorry, I've tried to come up with a good synonym, but "stupid" fits here. My earlier use of "hipster" was my kind attept at an alternative, but this stuff really feels a little too much like a first-pass solution to be in a nice, mature templating library.

Labels: angularjs, noteToSelf, TIL

Step 1: How I chose React

What's an "ampersand binding" in AngularJS?

Where the ampersand binding bites you

The advantages of the AngularJS ampersand binding convention

Put another way...

What people usually end up doing... and why you shouldn't

Transclusion and uibModal

You don’t need defer to create a simple-valued promise