ShMcK

Component Router Lifecycle Hooks

Shawn McKay — Wed, 06 May 2015 13:09:55 GMT

Part 2: Component Router Lifecycle Hooks

& Using ES6 classes in Angular 1.x

In part 1 we looked at how router conventions help you stay organized and write less code.

Note: Component router is still in development & only available for Angular 1.3+

Now we'll look at something much more awesome. Using a multi-step form as an example, we'll see why you should take advantage of ES6 classes in Angular, and look at how to use component routers Lifecycle Hooks.

Project

Here's the scenario: you have a multi-step user sign-up form, and you want to save the user data whenever there is a route change.

First we'll need a service to save the data.

ES6 Classes as Services

This service will save our user form data to UserService.user.

We can use UserService.save(updates) to merge new form data objects with our user. For example, if our user has existing data, {name: 'Joe'}, we can push more updates {age: 24} to make a complete user object {name: 'Joe', age: 24}.

class UserService {  
  constructor() {
    this.user = {};
  }
  save(updates) {
    function update(obj) {
      for (var i = 1; i < arguments.length; i++) {
        for (var prop in arguments[i]) {
          var val = arguments[i][prop];
          if (typeof val === 'object') {
            update(obj[prop], val);
          } else {
            obj[prop] = val;
          }
        }
      }
      return obj;
    }
    update(this.user, updates);
    // a Promise could be used here, returning false if there is an error. 
    return true;
  }
}

export default angular.module('app.services.user', [])  
  .service('UserService', UserService);

ES6 Classes as Controllers

Why use ES6 classes as controllers? Inheritance.

But first, let's make our UserFormCtrl and inject the UserService we just made.

export class UserFormCtrl {  
  constructor(UserService) {
    this.user = UserService;
    // bind ng-model to this.user
  }
}
UserFormCtrl.$inject = ['UserService'];

This is what we want all our User Form controllers to inherit from.

LifeCycle Hook: canDeactivate

The Component router has a cool new feature called lifecycle hooks. These are functions that can be run during phases of routing, they include:

canActivate
canDeactivate
deactivate
activate

I'll encourage you to read more about these hooks, but for the sake of brevity, let's focus on what we need.

We want the form to save before the route changes, so we're looking at the canDeactivate hook.

Let's adjust our FormCtrl class.

UserFormCtrl.prototype.canDeactivate = function () {  
  return this.User.save(this.form);
  // true = continue
  // false = stay with the current route. change fails.
};

Now we have a class UserFormCtrl that will save on route change to our UserService.

Extending an ES6 Class

We can now create a series of multi-step form views with corresponding controllers.

class UserProfileCtrl {}  
class UserDescriptionCtrl {}  
class UserGoalsCtrl {}  
//
export default angular.module('app.user.form', [])  
.controller('UserProfileCtrl', UserProfileCtrl)
.controller('UserDescriptionCtrl', UserDescriptionCtrl)
.controller('UserGoalsCtrl', UserGoalsCtrl);

These form controllers can gain the ability to save to UserService through inheritance.

class UserProfileCtrl extends UserFormCtrl {}  
class UserDescriptionCtrl extends UserFormCtrl {}  
class UserGoalsCtrl extends UserFormCtrl {}

In the view, bind your forms to the model this.user from UserFormCtrl and everything should work. Forms will be saved on route changes.

Conclusion

There are good reasons to use ES6 Classes for controllers and services rather than just functions. It's not just a style decision.

Also bear in mind, this is only scratching the surface of what you can do with the Component router's lifecycle hooks. These hooks are a great reason to try out the new router today.

Angular Component Router

Shawn McKay — Wed, 06 May 2015 12:15:24 GMT

Part 1: Component Router Conventions

The new-angular-router coming with Angular 1.3+ now has a name: Component router.

The Component router is aptly named, as it is designed to help break your project into components (such as directives).

Here's a brief overview of some structural changes:

It routes to components (directives), not templates/controllers
The routes are setup in a controller/class, not during a config phase
It uses default conventions to find templates & controller names

Let's take a look at comparison between the three popular routers in Angular: ngRouter, uiRouter, & the new router.

In this post, we'll look how naming using the Component router with naming conventions can help save you a lot of code.

Conventions

Conventions mean less code. But the magic behind the scenes, that is, the default template mapping and controller naming, can initially come with a lot of confusion.

Let's make a comparison with ui-router to see the repetition Component router is trying to avoid.

ui-Router Example

The popular ui-router is based on states.

  $stateProvider
      .state('abc', {
        url: '/abc',
        templateUrl: 'app/templates/abc.html',
        controller: 'AbcCtrl as vm'
      });

But not DRY enough (Don't Repeat Yourself). This method uses too much chalk.

Component Router Example

Component router comes with built in defaults of how to structure and find your code.

The router defaults assume where the template is located and what the controller will be named.

$router.config([{
      path: '/abc',
      component: 'abc'
}]);

Component router makes the following assumptions based on the component name.

templateUrl: '/components/abc/abc.html',
controller name: 'AbcController'
controllerAs: 'abc'

If you're using compound names, Component router uses snake-case for templates & camelCase for scripts.

$router.config([{
      path: '/defGhi',
      component: 'defGhi'
}]);

templateUrl: '/components/def-ghi/def-ghi.html'
controller name: 'DefGhiController'
controllerAs: 'defGhi'

To keep things easy, just organize your components in the components folder by a snake-cased name. Everybody's happy.

Not happy? If you're not going to let a router tell you how to organize your code, read on. Otherwise, you can leave it at that.

Editing Conventions

These conventions can be edited to your own liking use the $componentLoaderProvider. It's a provider, so run it in the .config() stage.

Change Controller Name

Perhaps you like to name your controllers. You can use the $componentLoaderProvider.setCtrlNameMapping function which takes the component name and returns the new default controller name.

Controller: CapitalizedCtrl

.config(function($componentLoaderProvider) {
      $componentLoaderProvider.setCtrlNameMapping(function (name) {
            // where name is the component name
            var capitalized = name.charAt(0).toUpperCase() + name.slice(1);
            return capitalized + 'Ctrl';
      });
}

The path to your templates can be changed using the $componentLoaderProvider.setTemplateMapping function which takes the component name and returns a path to the default template.

Template: states/component-name.html

.config(function($componentLoaderProvider) {
      $componentLoaderProvider.setTemplateMapping(function(name) {
            var snakeCased = name.match(/[A-Z]*[^A-Z]+/g).join('-');
            return '/states/' snakeCased + '.html';
  });
}

Conclusion

The Component router keeps your code DRY, forcing you to design your app in components, maximizing your use of directives, and using common conventions. It can be frustrating to get started with the Component Router without knowing the defaults, but personally, I've grown to appreciate it.

In part 2 we'll look into using Component router's lifecycle hooks to work some magic, as well as how to take advantage of using ES6 class inheritance.

Webpack & Angular: Part 3

Shawn McKay — Wed, 15 Apr 2015 02:37:27 GMT

Part 3

6 Ways to use Webpack Require with Angular

For some reason, Webpack & Angular reminds me of late 90s Acne commercials.

It keeps your code: clean, clear & under control

What a terrible way to start a blog post, but I'll stick with it. No regrets.

In Part 1 & Part 2 we prepared setting up the project, all for this moment. Let's take advantage of using Webpack & Angular for creating modular code.

What is Required

In this demo we'll keep it simple and make a navbar directive, looking at the different ways of using require.

1. require('module').name

First of all, we'll need a module for handling our layout directives.

/app/core/layout.js

export default angular.module('app.layout', [])

We can simply require the layout by its (path).name, allowing us to change module names at any time.
Just make the loaded module a dependency.

/app/index.js

module.exports = angular.module('app', [  
  /* 3rd party */
  'lumx',
  /* modules */
  require('./core/layout').name
]);

2. Modular Directive Names

This makes it easy to change directive names in separate files with ease.

Let's start by setting up the navbar template.

/app/core/nav/nav.html

  
  
  
    
      {{::nav.app.title}} 
      v{{::nav.app.version}}
    
  
  
  
    
      
        
          {{::n.text}}

Add some style:

/app/core/nav/nav.scss

.header {
  position: fixed;
  top: 0;
  right: 0;
  left: 0;
  z-index: 999;
  height: 60px;
  padding: 12px;
  color: white;
  background-color: #4fc1e9;
  box-shadow: 0 1px 2px rgba(0, 0, 0, 0.3);
}

For the full nav.scss file, get it on Github. This is a short/ugly version.

Next add the directive & controller. Don't be confused, in this case my controller uses ES6 classes.

/app/core/nav/nav.js

class NavCtrl {  
  constructor() {
    this.app = {
      title: 'Module Loaders',
      version: '0.3.0',
      links: [{
        text: 'Webpack',
        link: 'http://webpack.github.io'
      }, {
        text: 'Require.js',
        link: 'http://requirejs.org/'
      }, {
        text: 'Jspm',
        link: 'http://jspm.io/'
      }]
    };
  }
}
export default () => {  
  require('./nav.scss');  // load styles for the component
  return {
    controller: NavCtrl,
    controllerAs: 'nav',
    templateUrl: './core/nav/nav.html'
  };
};

Notice the directive was never named. You really only need to name it once, on its angular.module.

/app/core/layout.js

export default angular.module('app.layout', [])  
  .directive('lumxNavbar', require('./nav/nav'));

This way, name changes remain very flexible even between files.

Add the directive to index.html and you should be able to see our working navbar.

/app/index.html

Nice!

3. require(templates)

This lumxNavbar templateUrl doesn't allow us to move things around very much. And the path is already getting long: app/core/nav/nav.html.

We can simplify this with the raw-loader. Install it as a dev dependency.

npm install -D raw-loader

Add another loader to our app/webpack.config.js file.

{
    test: /\.html/,
    loader: 'raw'
}

Note: Restart the webpack-dev-server for any config changes to take effect.
And now we can require html files using relative paths, this makes it much easier to move folders around.

/app/core/nav/nav.js

/* old templateUrl: './core/nav/nav.html' */
template: require('./nav.html')

4. require(json)

By now you're probably getting the hang of loaders. Just to be sure, let's load some json, get the json-loader.

npm install -D json-loader

Add it to the webpack.config.js.

//webpack.config.js

{
    test: /\.json/,
    loader: 'json'
}

We can put all of our main data into an index.json file, so when we make frequent navbar changes in the future, we won't have to dive into the nested /app/core/nav/nav.

/app/index.json

{
  "title": "Module Loaders",
  "version": "0.3.0",
  "links": [{
    "text": "Webpack",
    "link": "http://webpack.github.io"
  }, {
    "text": "Require.js",
    "link": "http://requirejs.org/"
  }, {
    "text": "Jspm",
    "link": "http://jspm.io/"
  }]
}

Let's require this file in nav.js

/app/core/nav/nav.js

class NavCtrl {  
  constructor() {
    this.app = require('../../index.json');
  }
}

But what if we move the nav folder around? Wouldn't an absolute path to app/index.json be more useful?

Luckily, with webpack we can use both.

5. require(absolute & || relative paths)

A relative path points to files relative to the current directory.

parent.js  
├── file.js
│   ├── folder
│   │       └──child.js

Parent ../parent.js
At the same level ./file.js
Nested ./folder/child.js

But if you want to move the folder or child.js around, the path will break.

Sometimes a relative path is best, but other times it's better to use an absolute path.

To use absolute paths with Webpack, we must first tell webpack.config our absolute root.

/app/webpack.config.js

module.exports = {  
  /* ... */
  resolve: {
    root: __dirname + '/app'
  }
};

Now we can point to our index.json file in a much cleaner way.
Note: Again, you'll have to restart the webpack-dev-server for any config changes to take effect.

class NavCtrl {  
  constructor() {
    /* old this.app = require('../../index.json'); */
    this.app = require('index.json');
  }
}

6. if (condition) { require('module') }

Say we want to run some angular optimizations, but only during production. Normally this would require a separate code base, but with Webpack we can nest modules within if statements.

For example, with ES6 modules, we can only import files at the top of the file. They cannot be wrapped in any blocks. Webpack's require is much more flexible.

The goal: if (mode === production) { load production optimizations }.

/app/core/config/production.js

export default (appModule) => {  
  appModule.config(($compileProvider, $httpProvider) => {
    /* less watchers from console debugging: https://docs.angularjs.org/guide/production */
    $compileProvider.debugInfoEnabled(false); 
    /* process multiple responses @ same time: https://docs.angularjs.org/api/ng/provider/$httpProvider */
    $httpProvider.useApplyAsync(true);
  });
};

Here we're loading the root appModule and providing it with some config optimizations.

Let's put in an if(){} statement to load production.js only when we are using production mode.

/app/core/bootstrap.js

require('./vendor.js')();  
var appModule = require('../index');  
if (MODE.production) { // jshint ignore:line  
  require('./config/production')(appModule);
}
angular.element(document).ready(() => {  
  angular.bootstrap(document, [appModule.name], {
    //strictDi: true
  });
});

Notice a few optimizations using MODE.production. But where does MODE come from? We can let webpack know.

/app/webpack.config.js

module.exports = {  
/* ... */
plugins: [  
    new webpack.DefinePlugin({
      MODE: {
        production: process.env.NODE_ENV === 'production'
      }
    })
  ]
}

Production mode can now be called when declare the NODE_ENV=production.

NODE_ENV=production node node_modules/.bin/webpack-dev-server --content-base app

This method can also be used for loading angular-mocks during MODE.test, etc.

Conclusion

Webpack's require gives you a lot more flexibility for building modular apps.

But we're really only scratching the surface of what Webpack can do. Check out the docs for more.

And again, check out the codebase or post any issues on Github. If you have any suggestions or other uses, post a comment below.

Webpack & Angular: Part 2

Shawn McKay — Wed, 15 Apr 2015 02:37:15 GMT

Part 2

Complex Webpack Dependencies

If you're unfamiliar with Webpack, you might want to checkout Part 1 of this Article on setting up a project with Webpack. This demo will continue from the previous article's code-base.

In this article we'll look at loading different types of dependencies: scripts, styles, fonts, etc. using Webpack. We'll also compare and contrast loading modules from NPM & Bower.

LumX

LumX is a great Material Design based CSS Framework built for Angular.

I would argue LumX looks better in both style and code-style when compared to angular-material. Again, that's largely a matter of opinion.

LumX will make a good example as it comes with a lot of different types of dependencies: scripts, styles, fonts. Let's see how Webpack can combine them into a single bundle.js file.

Bower Setup

Make a bower.json file.

bower init

Get some practice pressing enter really fast and agree to all the defaults.

Create a file called .bowerrc in the root. This will move all our downloaded bower components into the specified directory.

{
  "directory": "app/bower_components"
}

We're going to need lumx, install it.

bower install --save lumx

We should let Angular know we're going to be using Lumx.

/app/index.js

module.exports = angular.module('app', [  
  'lumx'
]);

LumX comes with a party of dependencies. Look in app/bower_components and you'll see them all.

bower_components  
├── angular
├── bourbon            // Sass mixins
├── jquery
├── lumx                
├── mdi                // Material Design Icons
├── moment             // time
└── velocity            // jQuery animations

Bad news at this point.

Webpack Prefers NPM over Bower.

Don't worry, it'll work out.

NPM vs. Bower

It's true, Webpack can handle both CommonJS & AMD (asynchronous) modules. But Webpack has a preference: CommonJS.

Let's compare NPM and Bower for a minute.

NPM has nested dependencies, meaning that you can have different packages all loading different versions of lodash at the same time. It's very specific.

Bower, on the other hand, flattens dependencies. As such, it is often used on the front-end because, well, obviously, it isn't ideal to have 3 versions of jQuery loaded every time you visit a webpage.

Anyway, that information probably wasn't very helpful, but it's nice to know. To the point:

NPM and Bower aren't the same, and Webpack prefers NPM (CommonJS). According to the Docs:

In many cases modules from npm are better than the same module from bower. Bower mostly contain only concatenated/bundled files which are:

More difficult to handle for webpack More difficult to optimize for webpack Sometimes only useable without a module system So prefer to use the CommonJs-style module and let webpack build it. Source.

Luckily most packages have NPM & Bower equivalents, though there doesn't seem to be much interest in making LumX an NPM module. See the open issue and comment about how much you want more NPM!

Let's get emotional now and get rid of all of our Bower Lumx dependencies. If it's not NPM, it deserves a subtle level of disgust.

app/bower_components  
├── bourbon    
└── lumx

If you want to keep them from coming back, go into bower_components/lumx/bower.json and delete the dependencies. However, you'll just have to do this again if you update LumX in the future.

From here on in, we're going to try to NPM almost everything.

NPM! NPM!

Now let's NPM install the dependencies we just deleted from Bower.

                               /* NPM Package Name */
"dependencies": {               ====================
    "angular": "latest",        // angular
    "jquery": "latest",            // jquery
    "velocity": "latest",        // velocity-animate
    "moment": "latest",            // moment
    "bourbon": "latest",        // node-bourbon (not necessary)
    "mdi": "1.0.8-beta"            // mdi
  }

As you can see, there really are easy NPM equivalents. Install the dependencies.

npm install --save angular jquery velocity-animate moment mdi@1.0.8-beta

Require(NPM_Module)

It should still work. Now let's load some primary NPM dependencies in a file we'll call vendor.js.

/app/core/vendor.js

module.exports = function () {  
    /* must be in order */
  require('jquery');
  require('velocity-animate');
  require('angular');
};

LumX seeks a few dependencies as globals, so we'll have to change this a little.

global attaches a value to the global context, likely the browser window.

/app/core/vendor.js

module.exports = function () {  
global.$ = global.jQuery = require('jquery');   // $ for Lumx, jQuery for velocity  
  require('velocity-animate');
  require('angular');
  global.moment = require('moment');            // for LumX
  };

Require(Bower_Component)

We'll have to inject some dependencies into LumX to get it to load properly. For this we need the imports-loader.

npm install -D imports-loader

Now we can require Lumx, even though it is a Bower package.

module.exports = function () {  
global.$ = global.jQuery = require('jquery');  
  require('velocity-animate');
  require('angular');
  global.moment = require('moment');
  require('imports?angular!../bower_components/lumx/dist/lumx.js');
  };

imports? tells webpack to use the imports-loader, and angular! says to inject angular into the file. You could also inject jQuery, but it's already global.

There is probably an easier to way load Bower packages, if you know how, please post in the comments. This worked for me.

Note: another possible suggestion would be to load Lumx as an NPM module using debowerify, as posted by Mallim here. I plan to explore this option later.

Require(styles)

LumX depends on a Bourbon Sass mixins which also have an NPM equivalent: node-bourbon. However, LumX requires them using a relative path within the bower_components folder, so it's better just to keep the Bower Bourbon file.

Style sheets can be loaded using require('.path/to/_lumx.scss'), as in the previous article but due to the cascading nature of stylesheets, it's likely better to keep them in a root index.scss file. Simply import the Lumx styles.

/app/index.scss

@import './bower_components/lumx/dist/scss/_lumx';

Require(Fonts & Icons)

We'll need another loader for fonts & icons. Install the file-loader.

npm install -D file-loader

Add the loader to your webpack.config file and tell it to grab anything that looks like a font.

/webpack.config.js

{
    test: /\.(woff|woff2|ttf|eot|svg)(\?v=[0-9]\.[0-9]\.[0-9])?$/,
    loader: 'file-loader?name=res/[name].[ext]?[hash]'
}

Load up the Material Design Icons. The materialdesignicons.scss will point to our font files, which will get loaded by the file-loader.

/app/core/vendor.js

/* Styles */
  require('../index.scss');
  require('../../node_modules/mdi/scss/materialdesignicons.scss');

Create a test to see if icons and fonts are loading in index.html.

/app/index.html

Icon Test:  @Sh_McK

Conclusion

We now have our LumX dependencies running: scripts, styles, fonts & icons, oh my!

We saw how Webpack can load different file formats, as well as handle different module types (NPM or Bower). Webpack prefers NPM.

Checkout Github for the full codebase.

In Part 3 we'll finally be able to take advantage of using Webpack with Angular for creating incredibly modular code.

Webpack & Angular: Part 1

Shawn McKay — Wed, 15 Apr 2015 02:37:06 GMT

Part 1

Getting Started

There are a lot of module loaders out there: Require.js, JSPM using System.js, to name a few.

Eventually the JavaScript community will come around and land on a winning module loader. My guess is Webpack, or something very similar.

Go with Webpack. Webpack provides an elegant and multi-featured approach to module loading. It does everything I wanted it to do, and more. Really, a lot more.

Let's try it out. We'll setup a project using Webpack, including ES6 transpiling & Sass loading. In this example, we'll setup an Angular based project using Webpack.

Free free to load the basic project from Github.

File Setup

File Structure:

root  
├── app
│   ├── bower_components
│   ├── core
│   │       ├──bootstrap.js
│   │       └──vendor.js
│   │
│   ├── index.html
│   ├── index.scss
│   └──index.js
├── .jshintrc
├── node_modules
└── package.json

This should be the bare minimum required to check if everything is working.

/app/index.html

  
  
  
  
  Webpack & Angular
  
  
Angular is working: {{1 + 1 === 2}}

/app/index.js

alert('loaded!');

Webpack

Setup

Let's create a package.json file to get started.

npm init

Agree to whatever defaults.

We're going to need a few basic dev-dependencies to get started with webpack.

npm install -D webpack

Webpack will also require a webpack configuration file: webpack.config.js. Make the file and add the following:

/webpack.config.js

'use strict';  
var webpack = require('webpack'),  
path = require('path');  
// PATHS
var PATHS = {  
  app: __dirname + '/app',
  bower: __dirname + '/app/bower_components'
};
module.exports = {  
    // config goes here
};

Webpack is a lot easier than it looks. You just need to provide an entry and an output.

Notice bundle.js is the only script we needed to load in our index.html. Everything will go into that bundle.

Later you can have multiple bundles for easy lazy-loading and code-splitting.

/webpack.config.js

module.exports = {  
    context: PATHS.app,
     entry: {
           app: './index.js'
    },
    output: {
        path: PATHS.app,
        filename: 'bundle.js'
    }
}

We now have a module loader.

Let's build our bundle in the terminal.

webpack

This should create the app/bundle.js file. Check it out. It's mostly a bunch of webpack__require statements.

Webpack-Dev-Server

Webpack-dev-server is a quick and easy Node.js/Express/Socket.io app that creates your bundle.js file on the fly and reloads it on changes.

Install it as a dev-dependency.

npm install -D webpack-dev-server

But wait, there's more!

Hot Mode

Hot mode = live-reload of modules. No need to reload the entire project on every change, just load what changed. It makes sense and it's awesome.

It's not much work either. Update your webpack.config file.

/webpack.config.js

entry: {  
    app: ['webpack/hot/dev-server', './index.js']
  }

You may want to install webpack-dev-server globally. Otherwise you'll have to run it the long way: node node_modules/.bin/webpack-dev-server --content-base app/ --hot

Run it.

npm install -g webpack-dev-server  
webpack-dev-server --content-base app/ --hot

Open up http://localhost:8080/webpack-dev-server/.

It's hot.

/app/index.js

alert('hot-loaded!');

It updates amazingly fast. Again, unlike Gulp or Grunt, Webpack only needs to re-compile the module that changed.

Targeted reloading might not be important to you now, but as your project grows in size & complexity it becomes increasingly useful.

Quick Start

If you're used to using Gulp or Grunt, you probably like the time saving gulp serve, grunt serve shortcuts for running your app.

This can be accomplished with package.json scripts.

/package.json

"scripts": {
    "start": "webpack-dev-server --content-base app --hot"
  }

Now run npm start. Again, the app can be found at localhost:8080/ by default, or localhost:8080/webpack-dev-server for the hot-module version.

Bootstrap Angular

I like to bootstrap Angular, rather than adding ng-app="app" into the html.

/app/core/bootstrap.js

/*jshint browser:true */
'use strict';  
// load Angular
require('angular');  
// load the main app file
var appModule = require('../index');  
// replaces ng-app="appName"
angular.element(document).ready(function () {  
  angular.bootstrap(document, [appModule.name], {
    //strictDi: true
  });
});

Notice require('angular')? That replaces adding