AngularJS: Sharing data between controllers

Even though you should try to keep things decoupled and your directives, controllers and services should rather be self contained, you sometimes do need to share data between controllers. There are basically two main scenarios:

  1. Sharing data between a parent and a child controller
  2. Sharing data between two mostly unrelated controllers e.g. two siblings

Sharing data between a parent and a child controller

Let’s assume you have two controllers, one controller being the parent controller and a child controller:

<div ng-controller="ParentCtrl">
  <div ng-controller="ChildCtrl as vm">
  </div>
</div>

Where the controllers are defined as:

var app = angular.module('sharing', []);

app.controller('ParentCtrl', function($scope) {
});

app.controller('ChildCtrl', function($scope) {
});

Let’s now define a user name in the parent controller:

app.controller('ParentCtrl', function($scope) {
  $scope.user = {
    name: "Henri"
  };
});

Note that you shouldn’t define your variable as a primitive in the scope since this will cause shadow property to appear in the child scope hiding the original property on the parent scope (caused by the JavaScript prototype inheritance). So you should define an object in the parent scope and defined the shared variable as a property of this object.

There are now three ways to access this shared variable:

  1. using $parent in HTML code
  2. using $parent in child controller
  3. using controller inheritance

Using $parent in HTML code

You can directly access variables in the parent scope by using $parent:

Hello {{$parent.user.name}}

Using $parent in child controller

Of course, you could also reference the shared variable using $parent in the controller and expose it in the scope of the child controller:

app.controller('ChildCtrl', function($scope) {
  $scope.parentUser = $scope.$parent.user;
});

Then, you can use this scope variable in your HTML code:

Hello {{parentUser.name}}

Using controller inheritance

But since the scope of a child controller inherits from the scope of the parent controller, the easiest way to access the shared variable is actually not to do anything. All you need to do is:

Hello {{user.name}}

Sharing data between two mostly unrelated controllers e.g. two siblings

If you need to share data between two controllers which do not have a parent-child relationship, you can neither use $parent nor rely on prototype inheritance. In order to still be able to share data between such controllers, you have three possibilities:

  1. Holding the shared data in a factory or service
  2. Holding the shared data in the root scope
  3. Using events to notify other controller about changes to the data

Holding the shared data in a factory or service

AngularJS factories (and services) can contain both methods (business logic) and properties (data) and can be injected in other components (e.g. your controllers). This allows you to define a shared variable in a factory, inject it in both controllers and thus bind scope variables in both controllers to this factory data.

The first step is to define a factory holding a shared value:

app.factory('Holder', function() {
  return {
    value: 0
  };
});

Then you inject this factory in your two controllers:

app.controller('ChildCtrl', function($scope, Holder) {
  $scope.Holder = Holder;
  $scope.increment = function() {
    $scope.Holder.value++;
  };
});

app.controller('ChildCtrl2', function($scope, Holder) {
  $scope.Holder = Holder;
  $scope.increment = function() {
    $scope.Holder.value++;
  };
});

In both controllers, we bind the Holder factory to a scope variable and define a function which can be called from the UI and updates the vale of the shared variable:

<div>
  <h2>First controller</h2>
  <button>+</button>{{Holder.value}}
</div>
<div>
  <h2>Second controller</h2>
  <button>+</button>{{Holder.value}}
</div>

No matter which “+” button you press, both values will be incremented (or rather the shared value will be incremented and reflected in both scopes).

Holding the shared data in the root scope

Of course, instead of using a factory or a service, you can also directly hold the shared data in the root scope and reference it from any controller. Although this actually works fine, it has a few disadvantages:

  1. Whatever is present in the root scope is inherited by all scopes
  2. You need to use some naming conventions to prevent multiple modules or libraries from overwriting each other’s data

In general, it’s much cleaner to encapsulate the shared data in dedicated factories or services which are injected in the components which require access to this share data than making these data global variables in the root scope.

Using events to notify other controller about changes to the data

In case, you do not want to bind both scopes through factory data (e.g. because you only want to propagate changes from one scope to another one on some condition), you can also rely on event notifications between the controllers to sync the data. There are three functions provided by AngularJS to handle events:

  • $emit is used to trigger an event and propagate it to the current scope and recursively to all parent scopes
  • $broadcast is used to trigger an event and propagate it to the current scope and recursively to all child scopes
  • $on is used to listen to event notification on the scope
Using $emit

Since $emit is propagating events up in the scope hierarchy, there are two use cases for it:

  • Propagating events to parent controllers
  • Efficiently propagating events to unrelated controllers through the root scope

In the first scenario, you emit an event on the child controller scope:

$scope.$emit("namechanged", $scope.name);

And listen to this event on the parent controller scope:

$scope.$on("namechanged", function(event, name) {
  $scope.name = name;
});

In the second scenario, you emit an event on the root scope:

$rootScope.$emit("namechanged", $scope.name);

And listen to this event on the root scope as well:

$rootScope.$on("namechanged", function(event, name) {
  $scope.name = name;
});

In this case there is effectively no further propagation of the event since the root scope has no parent scope. It is thus the preferred way to propagate events to unrelated scopes (and should be preferred to $broadcast in such scenarios).

There is one thing you need to consider when registering to events on the root scope: in order to avoid leaks when controllers are created and destroyed multiple times, you need to unregister the event listeners. A function to unregistered is returned by $emit. You just need to register this function as a handler for the $destroy event in your controller, replacing the code above by:

var destroyHandler = $rootScope.$on("namechanged", function(event, name) {
  $scope.name = name;
});

$scope.$on('$destroy', destroyHandler);
Using $broadcast

Theoretically, you could also use $broadcast to cover two scenarios:

  • Propagating events to child controllers
  • Propagating events to unrelated controllers through the root scope

Effectively, the second use case doesn’t make much sense since you would basically trigger an event on the root scope and propagate it to all child scopes which is much less efficient than propagating and listening to events on the root scope only.

In the first scenario, you broadcast an event on the parent controller scope:

$scope.$broadcast("namechanged", $scope.name);

And listen to this event on the child controller scope:

$scope.$on("namechanged", function(event, name) {
  $scope.name = name;
});
Similarities and differences between $emit and $broadcast

Both $emit and $broadcast dispatch an event through the scope hierarchy notifying the registered listeners. In both cases, the event life cycle starts at the scope on which the function was called. Both functions will pass all exceptions thrown by the listeners to $exceptionHandler.
An obvious difference is that $emit propagates upwards and $broadcast downwards (in the scope hierarchy). Another difference is that when you use $emit, the event will stop propagating if one of the listeners cancels it while the event cannot be canceled when propagated with $broadcast.

Demo

You can see the code from this post in action on plunker:

When to use $timeout

$timeout is the angular equivalent to settimeout in JavaScript. It is basically a wrapper aroung window.settimeout. So the basic functionality provided by $timeout is to have a piece of code executed asynchronously. As JavaScript doesn’t support thread spawning, asynchronously here means that the execution of the function is delayed.

Differences to settimeout

There are basically 2 differences between using $timeout and using directly settimeout:

  1. $timeout will by default execute a $apply on the root scope after the function is executed. This will cause a model dirty checking to be run.
  2. $timeout wraps the call of the provided function in a try/catch block and forwards any thrown exception to the global exception handler (the $exceptionHandler service).

Parameters

All parameters of $timeout are optional (although it of course doesn’t make much sense to call it without any parameters).

The first parameter is a function which execution is to be delayed.

The second parameter is a delay in milliseconds. You should now rely though on the delay to be absolutely respected. The minimum delay should be of 4 milliseconds in all modern browsers (you can set a smaller value but will probably not see a difference).

The third parameter is a flag (i.e. boolean, true or false) which when set to true, will cause $timeout not to execute $apply once the function is executed.

All additional parameters will be handled as parameters for the provided function and will be passed to the called function.

Delayed function execution

So two of the scenarios when you would want to use $timeout (or settimeout in this case) is:

either when you want to execute a function later on:

var executeInTenSeconds = function() {
    //Code executed 10 seconds later
};

$timeout(executeInTenSeconds, 10000);

or when you want to execute a function when the execution of the current block is finished:

var executeLater = function() {
    //Code executed once we're done with the current execution
};

$timeout(executeInTenSeconds);

Additional parameters

$timeout passes all parameters after the third one to the function being called. You can thus pass parameters to the function like this:

var executeInTenSeconds = function(increment) {
    $scope.myValue += increment;
};

$timeout(executeInTenSeconds, 10000, true, 10);

This will basically execute executeInTenSeconds(10); after 10 seconds, trigger the global exception manager in case of an unhandled exception and run a digest cycle afterwards.

Model dirty checking

A scenario where you’d rather use $timeout than settimeout is when you are modifying the model and need a digest cycle (dirty check) to run after the provided function is executed e.g.:

var executeInTenSeconds = function() {
    //Code executed 10 seconds later
	$scope.myScopeVar = "hello";
};

$timeout(executeInTenSeconds, 10000);

After 10 seconds our function will be called, it will change the value of a scope variable and after that a digest cycle will be triggered which will update the UI.

But there are cases when you actually do not need a model dirty checking (e.g. when you call the server but do not need to reflect the results of this call in you application). In such cases, you should use the third parameter of $timeout (invokeApply) e.g.:

var executeInTenSeconds = function() {
    //Code executed 10 seconds later and which doesn't require a digest cycle	
};

$timeout(executeInTenSeconds, 10000, false);

When the third parameter of $timeout is set to false, $timeout will skip the $rootScope.$apply() which is usually executed after the provided function.

Global exception handler

Since $timeout also wraps the provided function in a try/catch block and forwards all unhandled exceptions to the global exception handler, you may also use it in other cases too. I personally feel this is just a solution for lazy developers as you should rather wrap your function code in a try/catch block e.g.:

function($exceptionHandler) {
	try {
	  // Put here your function code
	} catch (e) {
	  // Put here some additional error handling call
	  $exceptionHandler(e); // Trigger the global exception handler
	}
	finally {
	  // Put here some cleanup logic
	}
}

And instead of duplicating this code everywhere you should probably consider writing your own reusable provider e.g.:

'use strict';

function $ExceptionWrapperProvider() {
  this.$get = ['$exceptionHandler', function($exceptionHandler) {

    function exceptionWrapper(fn) {
        try {
			return fn.apply(null, arguments);
        } catch (e) {
          $exceptionHandler(e);
        }
		return null;
    }

    return exceptionWrapper;
  }];
}

$timeout without function

All parameters of $timeout are optional, even the function. So why would you need to call $timeout without a function ? Basically, if you call $timeout without a function, there is no function execution, thus no exceptions and all that remains is the delay and the digest cycle. So calling $timeout without a function e.g.:

$timeout(10000);

Basically just triggers a digest cycle after the provided delay. In the example above, it would cause a digest cycle to be run after 10 seconds. But of course doing this is probably a sign that something’s wrong in your application (you should need to run delayed digest cycles but should rather run them after some logic has been executed). But if something is run asynchronously outside of your code but you do not get called back when it’s done and this external code somehow modifies something in the angular scopes, you might need to handle it this way. In this case, using $timeout is not really different from using:

settimeout( function() {
	$rootScope.$apply();
}, 10000);

It’s just less lines of code…

Asynchronously pre-loading scripts with AngularJS and RequireJS

As your web application grows, the number and size of JavaScript files you will have to load grows as well. If you are using AngularJS and RequireJS, you might well reach a level where the initial loading of such resources takes so long that you need to start looking into better ways to handle loading these dependencies.

Initial Loading

Your starting point when working with AngularJS is that everything is loaded in the beginning:

initial loading

The advantages of this approach are that it’s very easy to handle and switching to the second or third view is extremely fast as everything was already loaded upfront.

Lazy loading

As described in this article, lazy loading can help reducing the initial loading time by loading resources on demand when the users moves to another view:

lazy loading

So with this approach the time required to switch from the initial view to another view is increasing (because you now need to load some resources first) but the initial load time is decreasing.

Asynchronous pre-loading

In order to get a low initial loading time and not require any loading time for the second and third view, you need to implement some asynchronous solution which relies on the fact that files which have already been loaded will not be loaded again and that the user usually doesn’t immediately switch to the second or third view.

The delay introduced by the user could be because he needs to enter some credential in a login page. Or the initial view is some kind of dashboard and the user will first review all displayed information before going to more detailed views.

asynchronous preloading

When the initial view is displayed, we require scripts needed for the other two views to be loaded asynchronously. So while the user is interacting with the initial view, the scripts are loaded in the background and once the user activates one of the other views, the scripts will not be loaded again.

Asynchronous pre-loading with AngularJS and RequireJS

In order to load JavaScript files asynchronously in the background, we’ll need to use the async version of require:

require(["module_name"])

There are basically 3 places where you could trigger this:

  1. Immediately
  2. In the resolve function of your route definition
  3. In the require callback of your view

The problem with the first option is that since it triggers the asynchronous background loading of the files immediately, these load operations will compete with the loading of other resources you are waiting for. This means that it will use some of the bandwidth you need for the synchronous loading of files and it will also use HTTP connections which might cause the other load operations to have to wait.

If you are dynamically loading files for the new view in your resolve function, putting the code to asynchronously load files you will need in the future has the same effect. It’s just maybe not that bad because the files which are lazy loaded might be less or smaller than the ones which are required for all views and loaded upfront.

So the solution I went for is the third. Since the background loading is triggered once the required files for the view have been loaded, it has no impact on other load operations.

I’ve updated the pluggableViews provider I’ve already described in a previous post to have an additional optional parameter called preload. It’s basically a function called in the callback of the require function call during lazy loading of the view. The default value for this function is an empty function:

if (!viewConfig.preload) {
    viewConfig.preload = function () {
    };
}

And it is called in the callback of the require function:

$routeProvider.when(viewConfig.viewUrl, {
	templateUrl: viewConfig.templateUrl,
	controller: viewConfig.controller,
	resolve: {
		resolver: ['$q', '$timeout', function ($q, $timeout) {

			var deferred = $q.defer();
			if (angular.element("#" + viewConfig.cssId).length === 0) {
				var link = document.createElement('link');
				link.id = viewConfig.cssId;
				link.rel = "stylesheet";
				link.type = "text/css";
				link.href = viewConfig.cssUrl;
				angular.element('head').append(link);
			}
			require([viewConfig.requirejsName], function () {
				pluggableViews.registerModule(viewConfig.moduleName);
				$timeout(function () {
					deferred.resolve();
					viewConfig.preload();
				});
			});
			return deferred.promise;
		}]
	}
});

I can then use it this way:

$pluggableViewsProvider.registerView({
	ID: 'walls',
	moduleName: "cards.walls",
	requirejsConfig: {paths: {'walls': '../views/walls/walls'}},
	preload: function () {
		require(['reports'], function () {
			console.log("reports loaded");
		});
		require(['admin'], function () {
			console.log("admin loaded");
		});
	}
});

Conclusion

Of course, introducing lazy loading and asynchronous background pre-loading increases the complexity of your application. And it is not trivial to introduce once you already have a large application which dependencies are a mess because you never need to clean them before (since by default AngularJS causes all files to be loaded upfront).

But if you load lots of files (especially JavaScript libraries), then making sure that files are loaded when needed and are not loaded at a point in time where this would slow down the application, will definitely help making your application look thinner and faster (from a user perspective).

About lazy loading AngularJS modules

I recently wrote a post about creating pluggable AngularJS views using lazy loading of Angular modules. After discussing this topic with colleagues, I realized I did provide a technical solution but not much background as to why it is useful, what should be lazy loaded and when does lazy loading make sense. Hence this post…

Does lazy loading always make sense?

First, as general rule, optimization should only be performed when you actually have a performance problem. Definitely not in a prophylactic way. This is a common error made by many software engineers and causing complexity to unnecessarily increase at the beginning of a project. If you identify a bottleneck while loading specific resources, you should start thinking about introducing lazy loading in order to speed up your app e.g. during initial loading.

But just lazy loading everything without first having a good reason to introduce it can very well result in worse performance. You need to understand that lazy loading could actually increase the overall cost of loading resources. By loading all resources upfront, you get a chance to combine your resources and reduce the number of HTTP requests to your server. By splitting the loading of resources, you then actually have less possibilities to reduce the overall resource consumption by combination. Especially when you are loading many small resources, the overhead of loading them individually increases. Since JavaScript code is relatively small compared to static assets like images, lazy loading could cause a higher request overhead.

Also loading resources on demand means that when the user of your application activates a view which has not yet been loaded, he first has to wait until the additional resources are lazy loaded and properly registered. When you load everything upfront, the user has a longer wait time on application load time but can immediately access all views in your application without delay.

So using lazy loading always means having a tradeoff between initial load time of the application and subsequent activation of parts of your application.

RequireJS vs. AngularJS Dependency Injection

RequireJS is currently the state of the art in modular script loader and asynchronous and lazy loading of JavaScript files. It is based upon the AMD (Asynchronous Module Definition) API. It handles loading your script files in the browser based on a description of dependencies between your modules.

This may sound similar to AngularJS dependency injection mechanism. But RequireJS and AngularJS DI work on two completely different levels. AngularJS DI handles runtime artifacts (AngularJS components). In order to work properly, AngularJS DI requires all of the JavaScript code to have been loaded and registered by the framework. It injects controllers, directives, factories, services, etc. which have been previously loaded.

Since there is no direct integration of RequireJS and AngularJS and AngularJS has a single initialization phase where the definition of modules is interpreted, when using both of them, RequireJS will need to first load the complete dependency tree before AngularJS DI can be used. This effectively means that your complete JavaScript code will need to be fetched on initial load.

So we cannot just lazy load all AngularJS modules JavaScript files with RequireJS after an AngularJS application has started because the AngularJS DI container wouldn’t handle the components created as a result of loading the JavaScript files. Instead, you need to manually handle all these components which have been loaded after the startup phase of your application.

What’s the point of lazy loading ?

Lazy loading components generally improves an application’s load time. If your web application takes many seconds to load all components ever required to interact with user, you will most probably experience a high bounce rate with users just giving up before they even get a chance to see how great your application is.

By lazy loading parts of your application, you can make sure that the views in your application which are used immediately by most users are available immediately. If a given user decides to use other (e.g. more advanced views), the application starts loading required components on demand.

Especially if you are building a web application which can be used on phone and tablets (which represents about 60% of the total web traffic now), you have to consider that most users will not have a 4G mobile connection and initial load times can become prohibitive in an environment where the download bandwidth is limited.

Loading time is a major contributing factor to page abandonment. The average user has no patience for a page to take too long to load. Slower page response time results in an increase in page abandonment. Nearly half of web users expect a site to load in 2 seconds or less, and they tend to abandon a site that isn’t loaded within 3 seconds.

So improving the initial load time of your web application is critical. And this is the main use case for lazy loading.

When and what to lazy load ?

As explained above lazy loading makes sense when you want to reduce the initial load times and are ready to accept that loading additional views might not be instantaneous. Ideally, at some point in time during the run time of your application, you would be able to determine that the user will need a specific view and load it asynchronously in the background. Unfortunately, this kind of smart lazy loading is very difficult to implement for two reasons. First, it is not so easy to predict that a user will need a specific view. Second, asynchronicity introduces additional problems which increase the complexity of your application.

This is why lazy loading is mostly implemented in such a way that when a user activates a view (or a sub-part) of your application which hasn’t yet been loaded, it is loaded on the fly before displaying it.

A loading mechanism can be implemented on different levels. Having a fine granular lazy loading mechanism, reduces the maximum wait time for the user when something is loaded. But the complexity of your application grows (potentially exponentially) as well, the more fine granular it is. Since our general rule is not to optimize upfront but only find a solution to problems you are actually facing, this requires a strategy along these lines:

  1. First load everything upfront (this is how most desktop applications work). If you face problems because of high initial load time, continue optimize. Otherwise you are done.
  2. Lazy load individual modules of the application. This is the way I handle lazy loading in the application I used as a basis for my previous post. If the load times are acceptable, then stop optimizing. “Acceptable” could either mean that the load times for all parts of the application are good enough or that the load times are good for 95% of the use cases and the user only has a longer wait time for rare use cases.
  3. Keep reducing the granularity of lazy loaded resources…
  4. Until the performance is acceptable.

AngularJS components vs. Module loading

If you google for AngularJS lazy loading, you will find many resources. Most of them teach you how to lazy load controllers, directives, etc. The difference between these approaches and i.e. the one described in my previous post is basically that when you just lazy load controllers and such, you have a single module which is initialized at the beginning and for which you register additional components on the fly. This approach has two drawbacks:

  1. You cannot organize your application in multiple AngularJS modules.
  2. This doesn’t work well for third-party party AngularJS modules.

Both of these drawbacks have the same root cause. Since AngularJS does not only rely on JavaScript files to be loaded but also need to have the modules properly registered in order to inject them using DI, if this step is missing because the files were loaded later on, new AngularJS modules will not be available.

That’s why you need to additionally handle the invoke queue, config blocks and run blocks when lazy loading new AngularJS modules.

Also note that whenever the term “module” is used in this context, it can mean two different things:

  1. AMD module as used in RequireJS. These modules just encapsulate a piece of code which has load dependencies to other modules. These are designed for asynchronous loading.
  2. AngularJS modules. These modules are basically containers for controllers, services, filters, directives…

When I reference modules in this article, I mean the second kind of modules.

Conclusion

I hope that with this article I made it clearer, why lazy loading AngularJS modules is not a stupid idea but should be handled carefully. You need to make sure that you choose the right level on which to lazy load components. And if you need to split your application in multiple modules or use third-party modules, it is definitely not sufficient to use most of the mechanisms you will find by quickly googling for lazy loading in AngularJS. Using RequireJS is definitely a first step in the right direction but you need to make sure that the loaded scripts are also made available to the AngularJS dependency injection container.

 

AngularJS: Stopping event propagation on ng-click

Let’s assume you have a link containing an additional icon e.g.:

<a href="" ng-click="doSomething()">
	<span class="glyphicon glyphicon-th-list" ng-click="doSomethingElse()"></span>
</a>

(this whole article of course only make sense if your <a> tag contains more than this or is displayed in such a way that it’s larger than the icon)

When you click outside of the <span> doSomething() will be called. But when you click on the <span> both doSomethingElse() and doSomething() will be called. This is because of event propagation. The click is processed by doSomethingElse and then the event propagates to the parent of the <span> tag i.e. the <a> tag and triggers doSomething().

Actually the fact that it’s an <a> tag doesn’t make much of a difference. If you replace the <a> tag by a <div> tag, you’ll get the same results.

In plain old JavaScript, you’d return false in your click handler to prevent event propagation. Doing this in doSomethingElse() unfortunately doesn’t help. doSomething() will still be called.

The code defining the ngClick directive looks like this (in AngularJS 1.3.15):

forEach(
  'click dblclick mousedown mouseup mouseover mouseout mousemove mouseenter mouseleave keydown keyup keypress submit focus blur copy cut paste'.split(' '),
  function(eventName) {
    var directiveName = directiveNormalize('ng-' + eventName);
    ngEventDirectives[directiveName] = ['$parse', '$rootScope', function($parse, $rootScope) {
      return {
        restrict: 'A',
        compile: function($element, attr) {
          // We expose the powerful $event object on the scope that provides access to the Window,
          // etc. that isn't protected by the fast paths in $parse.  We explicitly request better
          // checks at the cost of speed since event handler expressions are not executed as
          // frequently as regular change detection.
          var fn = $parse(attr[directiveName], /* interceptorFn */ null, /* expensiveChecks */ true);
          return function ngEventHandler(scope, element) {
            element.on(eventName, function(event) {
              var callback = function() {
                fn(scope, {$event:event});
              };
              if (forceAsyncEvents[eventName] && $rootScope.$$phase) {
                scope.$evalAsync(callback);
              } else {
                scope.$apply(callback);
              }
            });
          };
        }
      };
    }];
  }
);

So it’s not returning the return value of the function used in ng-click. So we have two ways of solving this.

The first solution is to pass the $event parameter to your function and call both stopPropagation() and preventDefault():

<a href="" ng-click="doSomething()">
	<span class="glyphicon glyphicon-th-list" ng-click="doSomethingElse($event)"></span>
</a>

And:

this.doSomethingElse = function($event) {
	// do something else
	$event.stopPropagation();
	$event.preventDefault();
};

If you do not want to add this code in all ngClick handlers, you can also use a directive which will install a click handler on the element and return false:

<a href="" ng-click="doSomething()">
	<span class="glyphicon glyphicon-th-list" ng-click="doSomethingElse()" stop-propagation></span>
</a>

And:

.directive('stopPropagation', function () {
	return {
		restrict: 'A',
		link: function (scope, element) {
			element.bind('click', function (e) {
				return false;
			});
		}
	};
});

Both ways work. I ended up using the first one because it doesn’t involve going around AngularJS to get this solved but it does pollute your JavaScript code. So use the second one if it’s a problem for you and you’d rather only add an attribute to your HTML code. The advantage of the second approach is that you can easily add this behavior to any element by just adding the attribute.

AngularJS: RequireJS, dynamic loading and pluggable views

I’ve been using AngularJS for some time now and find declarative templates, the testability and dependency injection great.What I especially like is that the fact that AngularJS prescribes and dictates quite a lot, you are forced to bring some structure to the code of your application. This tends to reduce the velocity of the degeneration you often observe in larger JavaScript projects, where chaos slowly takes over.

But one of the things which was bothering me was that I always ended up adding some libraries/modules and forgetting to add them to my index.html. And sometimes after the list of loaded scripts grew quite a lot, figuring out where to insert this new script tag is really a pain.

Introducing RequireJS

So I decided some time ago to start using RequireJS to bring order in what was slowly becoming a mess. RequireJS does exactly what’s missing when you only rely on the AngularJS dependency injection: a file loader which supports dependencies and a way to define dependencies non-angular scripts (plain old JavaScript files).

Defining your AngularJS modules as RequireJS AMD modules with dependencies just means wrapping them in  a call to the define function e.g.:

define([
    'angular',
    'moment'
], function (angular, moment) {
    return angular.module('admin', [])
    	.controller('AdminController', ...);
});

Instead of loading all the scripts, you can replace all script tags by one of them loading RequireJS and referencing your main JavaScript file where RequireJS will be configured:

<script src="vendor/requirejs/require.js" data-main="scripts/main"></script>

main.js will contain the RequireJS configuration e.g.:

require.config({
    paths: {
        jquery: "../vendor/jquery/dist/jquery.min",
        jqueryui: "../vendor/jquery-ui/jquery-ui.min",
        angular: "../vendor/angular/angular.min",
        ngRoute: "../vendor/angular-route/angular-route.min",
    },
    shim: {
        angular: {exports: 'angular', deps: ['jquery']},
        jqueryui: {deps: ['jquery']},
        jquery: {exports: '$'},
        ngRoute: ["angular"],
    }
});

You also need to manually bootstrap your application to make sure that RequireJS loads all required dependency first. This is done by removing the ng-app attribute from your index.html and instead calling angular.bootstrap in main.js e.g.:

require.config({
	...
});

require([
        'angular',
        'scripts/app'
    ], function (angular, app) {
        angular.element(document).ready(function () {
            angular.bootstrap(document, ['cards']);
        });
    }
);

This will load AngularJS, then load your app and then bootstrap your application.

Introducing RequireJS is actually quite some work (if all your files and modules are already there) but not really complex. The main issue I have faced was that there is no explicit dependencies between AngularJS and JQuery, so they might be loaded in any random order. If AngularJS is loaded before jQuery, it will revert to using jqLite which is definitely not sufficient for jQuery UI. This will lead to strange errors occuring. So what you need to do is make sure that jQuery is loaded before AngularJS. This can either be done by setting priorities in your RequireJS configuration (only works with RequireJS 1.x) or by making jQuery a dependency of AngularJS (in the shim section of RequireJS 2.x – see example above).

OK, after all small problem were solved and my application was running again, I looked back at what I had done and realized that even though I didn’t ever had to add a script tag to my main HTML file, it wasn’t yet as great as I thought it would be before I started moving to RequireJS. First, I still have to manage dependencies on 3 levels:

  1. Dependencies between files i.e. file load order
  2. Dependencies between AngularJS modules
  3. Dependencies to individual controllers or providers

The first kind of dependencies is now managed by RequireJS instead of having me manage it in index.html. The other two have not changed.

Moreover, my application still looked like a big monolithic application at runtime since even though the file load order was now computed by RequireJS based on dependencies, I was still loading all files and interpreting them at application start. No matter whether some modules, controllers, directives… might only be needed much later or for specific users not at all.

Introducing Lazy Loading

So I started looking into lazy loading. Luckily I quickly realized that the step introducing RequireJS in my application hadn’t been useless. It is indeed possible to lazy load controllers, directives and such in AngularJS without resorting to using RequireJS. But you then need to manage the JavaScript files containing them and their dependencies to external libraries manually. With RequireJS, all you need to do to have all required files loaded before registering the lazy loaded controllers, views and such is to wrap it all in a require call.

There are different levels of lazy loading which can be achieved in AngularJS (having different levels of difficulty and restrictions).

Dynamically Loading Controllers and Views

The first level of lazy loading is dynamically loading controllers and views to an already loaded AngularJS module. To associate views with controllers, you would typically put your routing code in a module’s config function:

$routeProvider
     .when('/customers',
        {
            controller: 'CustomersController',
            templateUrl: 'views/customers.html'
        })
    .when('/orders',
        {
            controller: 'OrdersController',
            templateUrl: 'views/orders.html'
        })
    .otherwise({ redirectTo: '/customers' });

This means that everything will be loaded at once at runtime using the $routeProvider object. The referenced controller must have already been registered or you will get an error while defining the routing. Lazy loading the views (i.e. the referenced template URL) is supported out of the box but the JavaScript code for your controllers needs to be loading upfront.

To allow lazy loading, you will need to use the resolve property (additionally to the templateUrl) and also make sure that your controllers are properly registered once the JavaScript file is loaded. So using RequireJS to load the scripts and their dependencies, your code would look like this:

$routeProvider.when('/customers', {
    controller: 'CustomersController',
    templateUrl: 'views/customers.html',
    resolve: {
        resolver: ['$q','$rootScope', function($q, $rootScope)
        {
            var deferred = $q.defer();
            require(['views/customers'], function()
            {
                $rootScope.$apply(function()
                {
                    deferred.resolve();
                });
            });
            return deferred.promise;
        }]
    }
});

This makes sure that your controller doesn’t need to present immediately but that the resolver function will be called when this route is activated. The resolver function returns a promise we create using $q.defer. In order to load all required files and AMD modules, we wrap the logic in this function in a require block. Once the loading of the script and all dependencies is done, our callback is called which just resolves the deferred object.

Now, there is still a problem. All files will be loaded but you won’t be able to use the new controllers because they were created after startup. In order to have them properly registered, you will need to overwrite a few functions of your angular module to use compiler providers (such as $controllerProvider) instead (this needs to be done before using the $routeProvider). So you’re application js file would look like this:

define([
    'angular'
], function (angular) {
    var app = angular.module('app', []);

    app.config(['$routeProvider',
        '$controllerProvider',
        '$compileProvider',
        '$filterProvider',
        '$provide',
        function ($routeProvider, $controllerProvider, $compileProvider, $filterProvider, $provide) {
            app.controller = $controllerProvider.register;
            app.directive = $compileProvider.directive;
            app.filter = $filterProvider.register;
            app.factory = $provide.factory;
            app.service = $provide.service;

            $routeProvider.when(...);

            $routeProvider.otherwise(...);
        }]);

    return app;
});

Now you will see that when you activate this view, not only the HTML template file will be loaded on the fly, but also the JavaScript file containing your controller. And your controller will be accessible from the view.

This approach works well and doesn’t require much additional code but it only works if the controller you’re lazy loading is controller on an existing module. And even if it is the case, you’ll notice it doesn’t work that well, when the controllers you are lazy loading bring their own dependencies (other modules with controllers and directives).

Registering AngularJS modules dynamically

So to have a more robust and versatile solution, we need to be able to register and activate AngularJS modules dynamically (and the modules on which they are dependent).

In order to do it, we first need to understand what happens when you load a new module at startup. A module contains the following data which are relevant when you want to dynamically activate it:

  • A list of dependencies: module.requires
  • An invoke queue: module.invokeQueue
  • A list of config blocks to be executed on module load: module.configBlocks
  • A list of run blocks to be executed after injector creation: module.runBlocks

When a module is registered, AngularJS checks whether all referenced modules are available.

Whenever you call a function on your module (e.g. config, run, controller, directive, service…), it just pushes the provided function to a queue. In case of config, the queue is module.configBlocks. For run, it goes to module.runBlocks. For the others, it’s module.invokeQueue.

On module load, AngularJS will concatenate the run blocks (but without executing them yet), run the invoke queue and then run the config blocks. Once the modules are loaded, all run blocks will be executed.

When loading modules dynamically, the phase when modules are usually loaded is over, so even though the JavaScript files are loaded by RequireJS, the modules will not be properly initialized. So we just need to perform manually what’s usually done automatically by AngularJS.

Module Dependencies

So the first step is to make sure that modules on which this module is dependent are activated first. So the function to load a module would start like this:

this.registerModule = function (moduleName) {
    var module = angular.module(moduleName);

    if (module.requires) {
        for (var i = 0; i < module.requires.length; i++) {
            this.registerModule(module.requires[i]);
        }
    }

    ...
};

The Invoke Queue

Each entry in the invoke queue is an array with three entries:

  1. A provider
  2. A method
  3. Arguments

So in order to process it, we need to have a list of providers:

var providers = {
    $controllerProvider: $controllerProvider,
    $compileProvider: $compileProvider,
    $filterProvider: $filterProvider,
    $provide: $provide
};

And invoke the appropriate method with the provided arguments:

angular.forEach(module._invokeQueue, function(invokeArgs) {
    var provider = providers[invokeArgs[0]];
    provider[invokeArgs[1]].apply(provider, invokeArgs[2]);
});

The Config and Run Blocks

To execute the config and run blocks, you can just rely on $injector:

angular.forEach(module._configBlocks, function (fn) {
    $injector.invoke(fn);
});
angular.forEach(module._runBlocks, function (fn) {
    $injector.invoke(fn);
});

The registerModule function

So the complete registerModule function would look like this:

this.registerModule = function (moduleName) {
    var module = angular.module(moduleName);

    if (module.requires) {
        for (var i = 0; i < module.requires.length; i++) {
            this.registerModule(module.requires[i]);
        }
    }

    angular.forEach(module._invokeQueue, function(invokeArgs) {
        var provider = providers[invokeArgs[0]];
        provider[invokeArgs[1]].apply(provider, invokeArgs[2]);
    });
    angular.forEach(module._configBlocks, function (fn) {
        $injector.invoke(fn);
    });
    angular.forEach(module._runBlocks, function (fn) {
        $injector.invoke(fn);
    });
};

Registering pluggable views

Now that we can we can register modules dynamically, we’re only one step away from defining views which can be plugged into our application. Imagine you have an application, with multiple views showing different (possibly unrelated) data. If you want others to be able to extend your application, you need to provide a way to define a pluggable view and load all such views setting the appropriate routes and providing some model which can be used to display the corresponding navigation links.

In order to store all data required for configuring the routing and creating the navigation links, we’ll be using an object (viewConfig). The routing (assuming you’re using ngRoute) is then configured this way:

    $routeProvider.when(viewConfig.viewUrl, {
        templateUrl: viewConfig.templateUrl,
        controller: viewConfig.controller,
        resolve: {
            resolver: ['$q', '$timeout', function ($q, $timeout) {

                var deferred = $q.defer();
                if (angular.element("#"+viewConfig.cssId).length == 0) {
                    var link = document.createElement('link');
                    link.id = viewConfig.cssId;
                    link.rel = "stylesheet";
                    link.type = "text/css";
                    link.href = viewConfig.cssUrl;
                    angular.element('head').append(link);
                }
                if (viewConfig.requirejsConfig) {
                    require.config(viewConfig.requirejsConfig);
                }
                require([viewConfig.requirejsName], function () {
                    pluggableViews.registerModule(viewConfig.moduleName);
                    $timeout(function() {
                        deferred.resolve();
                    });
                });
                return deferred.promise;
            }]
        }
    });
};

It provides the following configuration possibilities:

viewConfig.viewUrl: it’s the relative routing URL e.g. “/admin”
viewConfig.templateUrl: it’s the relative URL for the HTML template of the view e.g. “views/admin/admin.html”
viewConfig.controller: it’s the name of the controller for the view e.g. “AdminController”
viewConfig.navigationText: it’s the text displayed on the navigation link e.g. “Administration”
viewConfig.requirejsName: it’s the name of the RequireJS AMD module e.g. “admin”
viewConfig.requirejsConfig: it’s the object to be added to the RequireJS configuration e.g. { paths: { ‘admin’: ‘views/admin/admin’ } }
viewConfig.moduleName: it’s the name of the module being loaded e.g. “app.admin”
viewConfig.cssId: it’s the ID of the link tag created to load the CSS stylesheet e.g. “admin-css”
viewConfig.cssUrl: it’s the relative URL of the CSS stylesheet file e.g. “views/admin/admin.css”

In order not to have to define all these parameters every time we call the function to register the view, we’ll first define some defaults to be set when some of these parameters are not explicitly set:

if (!viewConfig.viewUrl) {
    viewConfig.viewUrl = '/' + viewConfig.ID;
}
if (!viewConfig.templateUrl) {
    viewConfig.templateUrl = 'views/' + viewConfig.ID + '/' + viewConfig.ID + '.html';
}
if (!viewConfig.controller) {
    viewConfig.controller = this.toTitleCase(viewConfig.ID) + 'Controller';
}
if (!viewConfig.navigationText) {
    viewConfig.navigationText = this.toTitleCase(viewConfig.ID);
}
if (!viewConfig.requirejsName) {
    viewConfig.requirejsName = viewConfig.ID;
}
if (!viewConfig.moduleName) {
    viewConfig.moduleName = viewConfig.ID;
}
if (!viewConfig.cssId) {
    viewConfig.cssId = viewConfig.ID + "-css";
}
if (!viewConfig.cssUrl) {
    viewConfig.cssUrl = 'views/' + viewConfig.ID + '/' + viewConfig.ID + '.css';
}

Using this, it’s sufficient to call our provider function like this in order to have a link added for our administration view:

$pluggableViewsProvider.registerView({ ID: 'admin', moduleName: "admin", requirejsConfig: { paths: { 'admin': 'views/admin/admin' } } });

Since the way the navigation links are displayed pretty much depends on how you do it in your markup, our provider will not do it itself but just store the corresponding information and provide it through the provider:

this.views = [];
...
this.views.push(viewConfig);

So the complete module for our provider looks like this:

(function () {
    'use strict';

    define([
        'angular'
    ], function (angular) {
        return angular.module('pluggableViews', [])
            .provider('$pluggableViews', [
                '$controllerProvider',
                '$compileProvider',
                '$filterProvider',
                '$provide',
                '$injector',
                '$routeProvider',
                function ($controllerProvider, $compileProvider, $filterProvider, $provide, $injector, $routeProvider) {
                    var providers = {
                        $compileProvider: $compileProvider,
                        $controllerProvider: $controllerProvider,
                        $filterProvider: $filterProvider,
                        $provide: $provide
                    };
                    this.views = [];

                    var pluggableViews = this;

                    this.registerModule = function (moduleName) {
                        var module = angular.module(moduleName);

                        if (module.requires) {
                            for (var i = 0; i < module.requires.length; i++) {
                                this.registerModule(module.requires[i]);
                            }
                        }

                        angular.forEach(module._invokeQueue, function(invokeArgs) {
                            var provider = providers[invokeArgs[0]];
                            provider[invokeArgs[1]].apply(provider, invokeArgs[2]);
                        });
                        angular.forEach(module._configBlocks, function (fn) {
                            $injector.invoke(fn);
                        });
                        angular.forEach(module._runBlocks, function (fn) {
                            $injector.invoke(fn);
                        });
                    };

                    this.toTitleCase = function (str)
                    {
                        return str.replace(/\w\S*/g, function(txt){return txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase();});
                    };

                    this.registerView = function (viewConfig) {
                        if (!viewConfig.viewUrl) {
                            viewConfig.viewUrl = '/' + viewConfig.ID;
                        }
                        if (!viewConfig.templateUrl) {
                            viewConfig.templateUrl = 'views/' + viewConfig.ID + '/' + viewConfig.ID + '.html';
                        }
                        if (!viewConfig.controller) {
                            viewConfig.controller = this.toTitleCase(viewConfig.ID) + 'Controller';
                        }
                        if (!viewConfig.navigationText) {
                            viewConfig.navigationText = this.toTitleCase(viewConfig.ID);
                        }
                        if (!viewConfig.requirejsName) {
                            viewConfig.requirejsName = viewConfig.ID;
                        }
                        if (!viewConfig.moduleName) {
                            viewConfig.moduleName = viewConfig.ID;
                        }
                        if (!viewConfig.cssId) {
                            viewConfig.cssId = viewConfig.ID + "-css";
                        }
                        if (!viewConfig.cssUrl) {
                            viewConfig.cssUrl = 'views/' + viewConfig.ID + '/' + viewConfig.ID + '.css';
                        }

                        this.views.push(viewConfig);

                        $routeProvider.when(viewConfig.viewUrl, {
                            templateUrl: viewConfig.templateUrl,
                            controller: viewConfig.controller,
                            resolve: {
                                resolver: ['$q', '$timeout', function ($q, $timeout) {

                                    var deferred = $q.defer();
                                    if (angular.element("#"+viewConfig.cssId).length == 0) {
                                        var link = document.createElement('link');
                                        link.id = viewConfig.cssId;
                                        link.rel = "stylesheet";
                                        link.type = "text/css";
                                        link.href = viewConfig.cssUrl;
                                        angular.element('head').append(link);
                                    }
                                    if (viewConfig.requirejsConfig) {
                                        require.config(viewConfig.requirejsConfig);
                                    }
                                    require([viewConfig.requirejsName], function () {
                                        pluggableViews.registerModule(viewConfig.moduleName);
                                        $timeout(function() {
                                            deferred.resolve();
                                        });
                                    });
                                    return deferred.promise;
                                }]
                            }
                        });
                    };
                    this.$get = function () {
                        return {
                            views: pluggableViews.views,
                            registerModule: pluggableViews.registerModule,
                            registerView: pluggableViews.registerView,
                            toTitleCase: pluggableViews.toTitleCase
                        };
                    }
                }]);
    });
}());

This is an example of how to use this provider in order to register pluggable views:

(function () {
    'use strict';

    define([
        'angular',
        'ngRoute',
        'pluggableViews',
        'views/nav/nav'
    ], function (angular) {
        var app = angular.module('cards', [
            'ngRoute',
            'pluggableViews',
            'cards.nav'
        ]);
        app.directive('navbar', function () {
            return {
                restrict: 'E',
                templateUrl: '../views/nav/nav.html'
            };
        });
        app.config(['$routeProvider',
            '$pluggableViewsProvider',
            function ($routeProvider, $pluggableViewsProvider) {
                $pluggableViewsProvider.registerView({
                    ID: 'walls',
                    moduleName: "cards.walls",
                    requirejsConfig: {paths: {'walls': 'views/walls/walls'}}
                });
                $pluggableViewsProvider.registerView({
                    ID: 'admin',
                    moduleName: "cards.admin",
                    requirejsConfig: {paths: {'admin': 'views/admin/admin'}}
                });
                $pluggableViewsProvider.registerView({
                    ID: 'reports',
                    moduleName: "cards.reports",
                    requirejsConfig: {paths: {'reports': 'views/reports/reports'}}
                });

                $routeProvider.otherwise({redirectTo: '/walls'});
            }]);

        return app;
    });
}());

In each view (which needs the navigation bar), I use the navbar directive which template contains the following:

<ul class="nav navbar-nav" ng-controller="NavigationController">
    <li ng-repeat="view in views track by $index" ng-class="navClass(view.ID)"><a href='#{{view.viewUrl}}'>{{view.navigationText}}</a></li>
</ul>

And the NavigationController gives us access to the views configured:

'use strict';
define([
    'angular',
    'pluggableViews'
], function(angular) {
    angular.module('cards.nav', [
        'pluggableViews'
    ])
        .controller('NavigationController', ['$scope', '$location', '$pluggableViews', function ($scope, $location, $pluggableViews) {
            $scope.navClass = function (page) {
                var currentRoute = $location.path().substring(1) || 'home';
                return page === currentRoute ? 'active' : '';
            };

            $scope.views = $pluggableViews.views;
        }]);
});

In this example, the pluggable views registered are hardcoded in my application but having a separate file containing the view configuration is fairly easy and would be a way to make your views truly work as plugins.

So that’s it for this post. We’ve build an provider which allows us to register views on the fly considering their dependencies and allowing the navigation bar or panel to be extended. Of course, you’ll still need to add some error handling, some logic to make sure that modules you depend on do not get activated multiple times… But this is all for a next post.

AngularJS: Running a directive after data has been fetched

In one of my AngularJS projects, I am using the angular-split-pane directive which is basically wrapping the split-pane JQuery plugin. This directive finds out how to split the panes and position the slider by reading the height and width attributes of the HTML tag.

I needed to add a functionality to my application so that the position of the slider is written to some session file on the server and reused next time the application is started to reposition the sliders at the same position, basically setting the height of the lower pane in percentage.

The previous position is fetched using $http. The problem is that it runs asynchronously and by the time the results are there, the directive has already been processed and changing the height tag has no effect anymore.

You can define the order in which directives are run by setting the priority property. But I needed a way to have the directive processed after the results from the server were available, not after or before another directive is processed.

After searching for a solution for quite some time, I finally find a way of implementing it late at night. This is actually pretty simple but for some reason it took me forever to think about such a solution.

When I fetch the data from the server I set some variable in my scope e.g.:

$http.get("../api/Config/").success(function(data) {
	sessionModel.ui = data;
});

Since I only want to execute the directive once the data is fetched, this means I want to have it executed once sessionModel.ui has a value. So all I need to do is add an ng-if attribute to my tag. Since the variable is initially not set, AngularJS will remove the element from the DOM and once the value is set, it will recreate it having the directive executed. So my tag would now look like this:

<split-pane ng-if="sessionModel.ui">

Of course the small disadvantage of this solution is that my UI is first shortly rendered without the split pane and when the data has been fetched, the split-pane is also rendered. In order not to have a partial rendering of the UI, you could of course move the ng-if attribute higher in your HTML code so that the whole UI is only rendered once the data from the server is available.

If your directive is not replacing the DOM element but just manipulating them, another solution would be to have the logic run asynchronously using $timeout and repeat until the data from the server is available. Or having it applied once the data is available by using $watch.

AngularJS: binding HTML code with ng-bind-html and $sce.trustAsHtml

I am working on a project in which based on some user interactions I am calling a service on the server and receive some pieces of HTML code which I need to display in the UI.

Of course I could just inject them in the DOM but to keep it clean I wanted to just store the HTML in the scope and bind it to an HTML tag. Basically doing something like this:

<!DOCTYPE html>
<html>

<head>
  <script src="https://code.angularjs.org/1.4.0-beta.6/angular.js" data-semver="1.4.0-beta.6" data-require="angular.js@*"></script>
  <link href="style.css" rel="stylesheet" />
  <script src="script.js"></script>
</head>

<body ng-app="myApp" ng-controller="myCtrl">
  <div ng-bind-html="myHtmlVar"></div>
</body>

</html>

The JavaScript code being:

var app = angular.module('myApp', []);

app.controller('myCtrl', function($scope) {
    $scope.myHtmlVar= "<a href='http://benohead.com'>benohead.com</a>";
});

This will unfortunately not work and you will get the following error message in the JavaScript console:

Error: [$sce:unsafe] Attempting to use an unsafe value in a safe context.

This basically means that the value we provided to ng-bind-html is not inherently safe and is also not marked as safe. So we need to mark it as trustworthy. This can be done by using $sce.trustAsHtml. An easy fix to the problem is to use the following:

app.controller('myCtrl', function($scope, $sce) {
    $scope.myHtmlVar= $sce.trustAsHtml("<a href='http://benohead.com'>benohead.com</a>");
});

If you do not want to add the calls to trustAsHtml everywhere in your code, you can also introduce a function in your scope and reference it in your page:

app.controller('myCtrl', function($scope, $sce) {
    $scope.myHtmlVar= "<a href='http://benohead.com'>benohead.com</a>";
    
    $scope.trustAsHtml = function(html) {
      return $sce.trustAsHtml(html);
    }
});

This function can then be called in the ng-bind-html attribute:

<div ng-bind-html="trustAsHtml(myHtmlVar)"></div>

Another way to do it is to define a filter which works in exactly the same way as the trustAsHtml function above:

app.filter('trustAsHtml', function($sce) {
  return function(html) {
    return $sce.trustAsHtml(html);
  };
});

app.controller('myCtrl', function($scope, $sce) {
  $scope.myHtmlVar = "<a href='http://benohead.com'>benohead.com</a>";
});

And use it like this:

<div ng-bind-html="myHtmlVar | trustAsHtml"></div>

Also note that if you want to set the HTML to the scope variable and then perform some DOM manipulation on this HTML code, you’ll run into a problem, because as long as your code is running, the data binding won’t be reflected until you return. Here is such an example:

app.controller('myCtrl', function($scope, $sce, $http) {
	$scope.myHtmlVar = "<a href='http://benohead.com'>benohead.com</a>";

	$scope.getHtmlCode = function (serviceParameter) {
		var responsePromise = $http.post("my-service-url", JSON.stringify(serviceParameter));
		responsePromise.success(function (data) {
			$scope.myHtmlVar = data;
			$scope.manipulateDom();
		});
	};
	
	$scope.manipulateDom = function () {
		//do some DOM manipulation on the retrieved HTML code...
	});
});

In order to execute some additional code, you’ll have to wrap it using $timeout:

app.controller('myCtrl', function($scope, $sce, $http, $timeout) {
	$scope.myHtmlVar = "<a href='http://benohead.com'>benohead.com</a>";

	$scope.getHtmlCode = function (serviceParameter) {
		var responsePromise = $http.post("my-service-url", JSON.stringify(serviceParameter));
		responsePromise.success(function (data) {
			$scope.myHtmlVar = data;
			$timeout(function() {
				$scope.manipulateDom();
			});			
		});
	};
	
	$scope.manipulateDom = function () {
		//do some DOM manipulation on the retrieved HTML code...
	});
});

 

AngularJS: Using Plupload in a dialog

Plupload is a very configurable JavaScript library you can use to allow your users to upload images. I’ve already used it in a few projects. I now wanted to use it in my current AngularJS project. Integrating Plupload in an AngularJS project is not especially difficult. There are already a few articles showing how this can be done. But it gets more difficult, when you try to integrate it into a dialog.

When initialized, Plupload puts an overlay above the browse button. This unfortunately only works if this element is displayed. If it is not displayed, the Plupload initialization will fail.

When working with dialogs, this means you need to execute the initialization of Plupload once the dialog is already displayed.

Let’s assume you have the use the following method to open a dialog using ngDialog:

$scope.uploadFile = function(){
	ngDialog.open({
		template: '/template/fileUploadDialog.html',
		controller: 'FileUploadController'
	});
};

and your controller looks like this:

app.controller('FileUploadController', function($scope){
	$scope.uploader = new plupload.Uploader({
		browse_button: 'browse',
		url: 'upload.php'
	});

	$scope.uploader.init();
});

Or if you are using angular-dialog-service:

$scope.uploadFile = function () {
	dialogs.create('/template/fileUploadDialog.html', 'FileUploadController', {}, {
		'backdrop': false,
		'size': 'sm',
		'copy': false,
		'windowClass': 'dialog-type-primary'
	});
};

and the same controller.

You will see that although you do not get any kind of error, nothing will happen when you click on the browse button. This is because no overlay was added by Plupload. If you put a breakpoint in the controller code, you will see that the dialog is not yet displayed when the code runs.

This is because Plupload has issues rendering inside elements which are hidden at initialization time You need to “refresh” Plupload after the dialog has been displayed:

$scope.uploader.refresh();

Now we know the root cause of the problem, all we need to do is either call the refresh method after displaying the dialog or just initialize Plupload after displaying the dialog. The problem is that I never found out how to provide a callback to get triggered after the dialog has been displayed.

After googling for it with no result, I decided to do it with a hack (won’t win a design price with this one but it works). Assuming the dialog will never take more than 300 milliseconds to display and the user will need at least 300 milliseconds to find the browse button, you can just solve it by executing some code asynchronously using setTimeout or $timeout (since we work with AngularJS):

app.controller('FileUploadController', function($scope, $timeout){
	$scope.uploader = new plupload.Uploader({
		browse_button: 'browse',
		url: 'upload.php'
	});

	$timeout(function () {
		$scope.uploader.init();
	}, 300);
});

Now your browse button should be working.

Drag&Drop with AngularJS

I am working on a project where I have a board containing different lanes (a kind of grid) on which you can place cards and move them according to their completion status. In order to implement the drag&drop functionality, I am using the angular-dragdrop module.

It is a wrapper for jQueryUI draggable/droppable components which makes it easy to implement drag and drop functionality in AngularJS.

In order to install the module, just run the following in your terminal:

bower install angular-dragdrop

Then in order to load it, you need to reference its JavaScript file, just after the reference to angular.js (and also a reference to jQuery and jQuery UI which are used by this module):

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
<script src="//ajax.googleapis.com/ajax/libs/jqueryui/1/jquery-ui.min.js"></script>
<script src="bower_components/angular/angular.js"></script>
<script src="bower_components/angular-dragdrop/src/angular-dragdrop.min.js"></script>

And add a dependency in your main module e.g.:

angular.module('myapp', [ 'ngDragDrop' ]);

Now, you’re ready to define draggable elements and droppable areas.

First, let’s make the card elements draggable. My elements looked like this before the change:

<div class="card">
	...
</div>

You need to add three custom attributes to this element:

<div class="card"
	 data-drag="true"
	 data-jqyoui-options="{revert: revertCard,
							helper: 'clone',
							appendTo: 'body',
							zIndex: 350}"
	 jqyoui-draggable="{index: 0,
						placeholder:true,
						animate:true,
						onStart: 'startCallback'}">
	...
</div>

jqyoui-draggable contain options passed to hte angular-dragdrop module. data-jqyoui-options contains the options passed to jQuery UI Draggable.

I’ve just copied the index, placeholder and animate options from some example, so you’ll have to use Google to find more info on them.

revertCard and startCallBack are functions on my controller which are used to control the way the draggable element react.

The zIndex is set so that the element is on top of all other elements while dragged. In my first try, I hadn’t set the appendTo and helper options. Since my draggable elements where contained in a container on which the overflow property was set, I could not move it out of its container. That’s because the element being dragged still had the same parent as the original element.

So you need to attach the element being dragged to the body of the page so that it can be moved anywhere. Unfortunately, attachTo with the “body” value only works if the helper option is set to “clone” i.e. it will not detach the element from its current container and attach it to the body but needs to work with a clone of the element which can be attached to the body.

The drawback is that the original element is still displayed. This is fine if you are writing an editor with some toolbox and want to use drag&drop to create new instances of this element. But if you actually want to move the element, it just doesn’t look good. So you need to additionally hide the original element while its clone is being dragged. That’s what is done in the startCallback of my controller:

$scope.startCallback = function (event, ui) {
	var $draggable = $(event.target);
	ui.helper.width($draggable.width());
	ui.helper.height($draggable.height());
	$draggable.css('opacity', '0');
};

This callback does two things:

  1. It makes sure that the clone element doesn’t grow to take up the whole screen (because its size is not limited by its parent anymore).
  2. It hides it by setting its opacity to 0.

In one of my early tries, I had hidden the original element by using display:none. The problem is that all other elements in this container would then move because this element was not displayed anymore. But setting its opacity to 0, it works as an empty placeholder.

Later on, once the dragging is stopped, I’ll make it visible again if required (only if it is not dropped at a valid location).

Usually, you will find that most example will set the revert option to “invalid”. This means that if you drop the component outside of a valid drop area, the helper will just come back to the original location and disappear. The problem is that since we’ve hidden the original element, you will end up with no element displayed at all. Thankfully, revert can also take a function as value. This is our second callback:

$scope.revertCard = function (valid) {
	if (!valid) {
		var that = this;
		setTimeout(function () {
			$(that).css('opacity', 'inherit');
		}, 500);
	}
	return !valid;
};

Returning false will cause the helper to return to the original location. The default duration of the animation is 500 milliseconds. Before returning true of false, we check whether the drop location was valid and if yes, we make the original element visible again. If we set the opacity to “inherit” immediately, the original element would be visible while the helper is moving back to the original location. That’s why we make the CSS change with a timeout of 500 milliseconds so that the original element is made visible as soon as the revert animation is finished.

Now we have a working draggable element and just need to define droppable areas where we can drop it:

<div class="lane"
	 data-drop="true"
	 jqyoui-droppable="{multiple: true,
						onDrop: 'dropCallback'}"
	 data-jqyoui-options="{hoverClass: 'ui-state-active',
							tolerance: 'pointer'}">
	...
</div>

The hoverClass is just used so that we can display the droppable area below the mouse pointer differently.

The tolerance option is used so that the element is dropped on the area below the mouse pointer and not on the area below the corner of the dragged element. This is useful when the dragged element is larger than the droppable areas.

We also define an additional callback in the controller:

$scope.dropCallback = function (event, ui) {
	var $lane = $(event.target);
	var $card = ui.draggable;
	if ($card.scope().card.lane != $lane.scope().lane.id) {
		$card.scope().card.lane = $lane.scope().lane.id;
	}
	else {
		$card.css('opacity', 'inherit');
		return false;
	}
};

This callback does two things:

  1. It updates the model so that the card is displayed on the lane it was dropped on.
  2. It prevents dropping the card on the lane it was on before dragging.

The first part is pretty straightforward. The second one just involves checking the original lane ID and the lane ID on which the drop operation is being performed. If they do not match we allow the drop. Otherwise we return false which is similar to a revert. Unfortunately, returning false doesn’t cause the revert callback to be called. So I have to change the opacity of the original element before returning false.

You’ll also notice that I do not set a timeout of 500 milliseconds. This is because returning false in the drop callback doesn’t cause a revert animation to be executed. I haven’t yet found out how to do this. So the helper just immediately disappears and I have to make the original element visible immediately.

That’s it ! It was actually pretty easy. Since you can set any draggable and droppable options without limitation, having this angular module between you and jQuery UI doesn’t seem to introduce any additional limitation. And since all references to event handler all point to callback in your controller, everything stays clean.

Update: I’ve also come accross an issue with a button on the card. I’m using the angular dialog service to display a dialog when a button on the card is clicked (using ng-click to trigger a function in my controller). At first, nothing happened when clicking on the button. This is because the mouse click didn’t go to the button. The solution was to increase the z-index of the button to 500 i.e. higher than the 350 configured for the draggable card.

Update: I’ve created a Plunker to show a working example.