Missing styleguide for component

[jejja]

Instead of using directives we can use component on those places where we dont need to DOM manipulate. But I cant find any styleguide for this in angularjs 1.5.

[johnpapa]

What suggestions does the community have for this?

I absolutely want a component section

[softsimon]

I like it this way:

(function() {
    'use strict';

    angular
        .module('app.widget.activeplaces')
        .component('activePlaces', {
            bindings: {
                data: '<'
            },
            templateUrl: 'components/active-places/active-places.widget.html',
            controller: ActivePlacesController,
            controllerAs: 'vm'
        });

    function ActivePlacesController(activityService) {
        var vm = this;

        vm.activities = [];
        vm.doFunnyStuff = doFunnyStuff;

        function doFunnyStuff() {
            vm.activities.push('yolo');
        }
    }

}());

Alternatively move component registration to the bottom:

(function() {
    'use strict';

    var activePlaces = {
        bindings: {
            data: '<'
        },
        templateUrl: 'components/active-places/active-places.widget.html',
        controller: ActivePlacesController,
        controllerAs: 'vm'
    };

    function ActivePlacesController(activityService) {
        var vm = this;

        vm.activities = [];
        vm.doFunnyStuff = doFunnyStuff;

        function doFunnyStuff() {
            vm.activities.push('yolo');
        }
    }

    angular
        .module('app.widget.activeplaces')
        .component('activePlaces', activePlaces);

}());

The problem is that I would prefer using the new $ctrl reference instead of vm which makes the vm-pattern inconsistent. So either switch completely to $ctrl or simply add controllerAs: 'vm' to the component settings object to be consistent with the rest of the style guide :)

[mgol]

I like the second way better. I'd also consider putting methods on a prototype to make it easier to migrate to ES6 classes later. I also agree it's time to switch to $ctrl as it's the default and not having to declare controllerAs reduces the boilerplate needed.

[gkalpak]

I prefer the first way fwiw 😁
_{(without vm of cource 😛)}

[tlenex]

First method is my presonal fav. I'd add to both controllers:

// other vm vars/assigns here
vm.$onInit = activate;

// functions
function activate() {
  // initialization magic here
}

of course we can change the name of activate function to init or onInit etc.

[xavhan]

This is a bit more opinionated and ES2016 but for my components I do it like that :

(function() {
  'use strict';
  /*
<active-places data="">
</active-places>
   */
  const componentConfig = {
    bindings: { data: '<' },
    templateUrl: 'components/active-places/active-places.widget.html',
    controller: ActivePlacesController,
  };

  /* @ngInject */
  function ActivePlacesController(activityService) {
    Object.assign(this, {
      activities: [],
      doFunnyStuff, 
      $onInit,
    })

    function $onInit() {
      activityService.list()
        .then(response => { this.activities = response })
        .catch(console.error)
    }
    function doFunnyStuff() {
      this.activities.push('yolo');
    }
  }
  angular
    .module('app.widget.activeplaces')
    .component('activePlaces', componentConfig);

}());

I like to have a copy-pastable snippet at the top of my file, that make me gain a lot of time. And it is more explicit and useful when developing in a project than the module and component declaration AMHO.
I also like the Object.assign (ES2015 could use angular.extend) call to bind all the methods and props to the component scope and also shave the file of all those little vm..
I use ES6 shorthand notation for objects when I can.
I also dropped the vm capture variable for the this use. Since ES2015, it is way more usable and since NG1.5+ I always find a way not to use $watch. Bonus effect, I learn to use it instead of running away from it.

[mikeerickson]

Here is a revision using ES6 if you are interested.

https://github.com/rwwagner90/angular-styleguide-es6

[softsimon]

This is also opinionated but I like to keep it simple. No vm, just $ctrl. No division of what to be exposed to the view. Thoughts?

    (function(){
        'use strict';

        angular
            .module('app.shared')
            .component('buttonList', {
                bindings: {
                    data: '<',
                },
                template: `<span ng-repeat="button in $ctrl.buttons">
                                <button class="btn btn-default" ng-click="$ctrl.removeButton(button)">{{ ::button.name }}</button>
                            </span>`,
                controller: MyDataController
            });

        function MyDataController(dataService) {

            this.$onInit = function () {
                this.buttons = [];
                this.loadData();
            };

            this.removeButton = function (button) {
                var index = this.buttons.indexOf(button);
                this.buttons.splice(index, 1);
            };

        }

    })();

[johnpapa]

I helped push the team for a .component feature for A1 ... and I am thrilled they did this.

I also voted very publicly for vm.* to continue in the A1 version of .component. But the community voted on the issue to go with $ctrl. In the spirit of the style guide, consistency is most important. As such, I think $ctrl is the best option here and it is in line with the defaults mentioned in your notes above.

Other things to consider are

1. how to define the configuration
2. how to set properties in the component (this, vm, $ctrl)
   2b. if using this (see # 2 above) how to handle new closures (e.g. self) ... yuk
3. Naming of the function (Component or Controller)
4. how to handle callbacks in bindings
5. naming of bindings

These are just some examples I grabbed out of the many ways I have seen and used .component thus far.

Let's keep the chat going on these and any other relevant ones.

[petebacondarwin]

I am keen on the 1st format that declares the component at the top. The reason is that the 2nd version introduces a new variable activePlaces, the name of which would need to be debated and which adds more complexity to reading the file.

I would also be keen to put the controller methods on the prototype. Unlike services, you can get multiple instances of controllers, especially if used in components, and it would seem more favourable not to be creating new copies of every method per instance.

Since components require a controller as, the default of $ctrl is my preferred option, you tend not to get context-free function calls so often of the controller methods.

I have always been calling the function [ComponentName]Controller since it is a controller for a component. I would recommend this, despite the fact that when we move to A2 these names would change - it would be a simple refactoring.

It is important in components to make use of the lifecycle hooks, rather than the controller constructor:

• constructor - only simple initialisation of properties, such as attaching injected services to properties. No real work should be done here, since going forward none of the bindings will be assigned here.
• $onInit - at this point the bindings and any required controllers have been assigned. This is where any real initialization work should be done.
• $onChanges - this is called whenever any of the input (<) and interpolation (@) bindings change. It is important to realise that mutation of input objects does not trigger the interpolation. But this is a good place to put code that reacts to changes to the inputs, which saves on creating watches. I would suggest that if you ar going for a "one-way data flow" approach then this is a good place to make a copy of the input objects as they change so that you don't inadvertently mutate an object that is passed.
• $onDestroy - the only reason for this method is to release or close long running resources that have been acquired or opened during the life of the component. Note that this hook does not get called if you manually destroy the component's isolate scope, nor if you manually remove the components element from the DOM. It only gets destroyed if the containing scope, the scope in which this component lives, is destroyed.

For output bindings I have been following the approach of having a handler method buttonClick(button) that actually triggers the output onButtonClick({$event: button}). And that the payload for the output is always put on the $event property. This means that on the outside you are able to do <button-list on-button-click="$ctrl.doStuff($event)"> which is similar to what you see in Angular 2.

So it all tends to look like this:

    (function(){
        'use strict';

        angular
            .module('app.shared')
            .component('buttonList', {
                bindings: {
                    buttons: '<',
                    onButtonClick: '&'
                },
                template: `<span ng-repeat="button in $ctrl.buttons">
                                <button class="btn btn-default" ng-click="$ctrl.buttonClick(button)">{{ ::button.name }}</button>
                            </span>`,
                controller: ButtonListController
            });

        function ButtonListController(dataService) {
            this.dataService = dataService;
        }

        ButtonListController.prototype = {
            $onInit: function () {
                this.dataService.loadData().then(function(data) {
                  this.data = data;
                }.bind(this));
            },
            $onChange: function(changes) {
                if (changes.buttons) {
                    this.buttons = angular.copy(this.buttons);
                }
            },
            buttonClick: function (button) {
              this.onButtonClick({ $event: { button });
            }
        };
    })();

[johnpapa]

@petebacondarwin I like what you have with a few changes.

I prefer not to embed the { } for the configuration for the component and instead to use a variable. I find this easier to read and debug. The name is irrelevant to me ...

var componentConfig = { ... };
angular
            .module('app.shared')
            .component('buttonList', componentConfig);

My larger concern is about the use of this and how functions can access the properties of the controller. The controller will have state ... yours has $ctrl.buttons in the template and I assume we'd have a this.buttons in the controller. When we create functions (prototype or otherwise) we have closures and some of those have their own this reference. This happens, for example, when we use $timeout(). How are you seeing these being resolved?