/angularAMD

Facilitate use of RequireJS in AngularJS

Primary LanguageJavaScriptMIT LicenseMIT

angularAMD v0.2.1 Build Status

angularAMD is an utility that facilitates the use of RequireJS in AngularJS applications supporting on-demand loading of 3rd party modules such as angular-ui.

Installation

bower

bower install angularAMD

cdn

//cdn.jsdelivr.net/angular.amd/0.2/angularAMD.min.js

Usage

http://marcoslin.github.io/angularAMD/ has been created as a working demo for angularAMD. The source code can be found in the www/ directory of this project.

Additional, the following project has been created to illustrate how to build an r.js optmized distribution:

RequireJS data-main

Starting point for any RequireJS app is a main.js, which should be used to define the components and their dependencies. Use deps to kick off app.js:

require.config({
    baseUrl: "js",
    paths: {
        'angular': '//ajax.googleapis.com/ajax/libs/angularjs/1.2.16/angular.min',
        'angularAMD': 'lib/angularAMD.min',
        'ngload': 'lib/ngload.min'
    },
    shim: {
        'angularAMD': ['angular'],
        'ngload': ['angularAMD']
    },    
    deps: ['app']
});

### Bootstrapping AngularJS

Once all component dependencies have been defined, use a app.js to create the AngularJS application and perform the bootstrapping:

define(['angularAMD'], function (angularAMD) {
    var app = angular.module(app_name, ['webapp']);
    ... // Setup app here. E.g.: run .config with $routeProvider
    return angularAMD.bootstrap(app);
});

Since bootstrapping is taking place manually, ng-app should not be used in HTML. angularAMD.bootstrap(app); will take care of bootstraping AngularJS.

On-Demand Loading of Controllers

Use angularAMD.route when configuring routes using $routeProvider to enable the on-demand loading of controllers:

app.config(function ($routeProvider) {
    $routeProvider.when(
        "/home",
        angularAMD.route({
            templateUrl: 'views/home.html',
            controller: 'HomeController',
            controllerUrl: 'scripts/controller'
        })
    );
});

The primary purpose of angularAMD.route is to set the .resolve property to load controller using a require statement. Any attribute you pass into this method will simply be returned, with exception of controllerUrl.

route without controllerUrl

You can avoid passing of controllerUrl if you define it in your main.js as:

paths: { 'HomeController': 'scripts/controller' }

route without controller

When the controller option is omitted, angularAMD.route assumes that a function will be returned from the module defined by controllerUrl. As a result, you can avoid giving an explicit name to your controller by doing:

define(['app'], function (app) {
    return ["$scope", function ($scope) {
        ...
    }];
});

Creating a Module

Any subsequent module definitions would simply need to require app to create the desired AngularJS services:

define(['app'], function (app) {
    app.factory('Pictures', function (...) {
        ...
    });
});

Here is the list of methods supported:

  • .provider **
  • .controller
  • .factory
  • .service
  • .constant
  • .value
  • .directive
  • .filter
  • .animation

** Only as of 0.2.x

Loading Application Wide Module

Normally, application wide features are created as independent modules and added as dependency to your app. 3rd party packages such as ui-bootstrap is a perfect example. However, what if you have a single directive? angularAMD simplifies such tasks by exposing the provider recipe so you can do something like:

directive/navMenu.js

define(['angularAMD'], function (angularAMD) {
    angularAMD.directive('navMenu', function (...) {
        ...
    });
});

app.js

define(['angularAMD', 'directive/navMenu'], function (angularAMD) {
    var app = angular.module(app_name, ['webapp']);
    ...
    // `navMenu` is automatically registered bootstrap 
    return angularAMD.bootstrap(app);
});

In this case, angularAMD.directive will detect that boostraping hasn't taken place yet and it will queue up the directive creation request and apply that request directly on the app object passed to angularAMD.bootstrap. If bootstraping has taken place already, it will essentially do the same thing app.directive. As a result, services created using angularAMD.<<recipe>> can be loaded before and after bootstraping.

3rd Party AngularJS Modules

3rd party AngularJS modules, meaning any module created using angular.module syntax, can be loaded as any normal JavaScript file before angularAMD.bootstrap is called. After bootstraping, any AngularJS module must be loaded using the included ngload RequireJS plugin.

define(['app', 'ngload!dataServices'], function (app) {...});

In case you need to load your module using the RequireJS plugin or if you have complex dependecies, you can create a wrapper RequireJS module as below:

define(['angularAMD', 'ui-bootstrap'], function (angularAMD) {
    angularAMD.processQueue();
});

In this case, all dependencies will be queued up and when .processQueue() is called, it will go through the queue and copy them into current app using app.register:

Module without .run or .config

If you have your own module that does not use .run or .config, you can avoid the use of ngload as any module created after bootstrap will support on-demand loading. For example:

common.js

define(['ngload!restangular'], function() {
    return angular.module('common', ['restangular']);
});

user.js

define(['common'], function(common) {
    common.factory("User", function () { ... });
});

controller/home_ctrl

define(['app', 'user'], function(app) {
    app.controller("HomeCtrl", ["$scope", "User", function ($scope, User) {
        ...
    }]);
});

In this example, the user package does not need to be loaded in the app.js as it's loaded on demand when HomeCtrl is called.

Running Sample Project

Prerequisites:

Run the following command after cloning this project:

npm install
grunt build
grunt serve-www
  • The default build will test angularAMD using following browsers: 'PhantomJS', 'Chrome' and 'Firefox'

History

This project was inpired by Dan Wahlin's blog where he explained the core concept of what is needed to make RequireJS works with AngularJS. It is a must read if you wish to better understand implementation detail of angularAMD.

As I started to implement RequireJS in my own project, I got stuck trying to figure out how to load my existing modules without re-writting them. After exhausive search with no satisfactory answer, I posted following question on StackOverflow. Nikos Paraskevopoulos was kind enough to share his solution with me but his implementation did not handle .config method calls and out of order definition in modules. However, his implementation gave me the foundation I needed to create angularAMD and his project is where the idea for alt_angular came from.

References