Directives, Scope, and Expressions

So in the previous post ng-app was used to mark tag where Angular would be rooted. In that tag we used an expression and could see that a value was being updated by seeing the correct output on the page. There was however a lot going on in the page. So let’s take a look at the last example again.

<!DOCTYPE html>
<html>
<head>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.2.14/angular.min.js"></script>
  <title>JS Bin</title>
</head>
<body ng-app ng-init="imperative = 'should';">
  These two lines should look identical.
  <br/>
  These two lines {{imperative}} look identical.
</body>
</html>

On the body tag we see ng-app and ng-init. These are tags that annotate the markup with new features. They are called Directives and Angular comes with many of them. They all work with scope. The scope is where all the values in the View live. A directive will either observe, update, or create values in the scope. Directives can even create new scopes. The scope is what is observed for changes in your data and it is what controllers will bind data to.

ng-app and ng-init

This directive is where the Angular app is created in the document. All other directives are either with it or in elements that are its descendants. ng-app being the root creates a the base scope. This scope has a special name; $rootScope. All other scopes will be descended from this one.

Now ng-init is run right after the scope is bound to the body tag. What is run is the value of the attribute, which in this case is “imperative = ‘should’;”. This value is an Expression. It may look like it is JavaScript but it is not. It is very like javascript but without any flow control logic. It is also unlike JavaScript in that as if it runs into an error, other expressions will continue to run.

Expressions

The code above actually has two examples of expressions. The first being apart of ng-init. Directives can evaluate values you pass to them as expressions. This means that as the values change in the scope the directive will respond to those changes. The second way to create an expression is in markup directly with double curly braces “{{” and “}}”. Back to the example we see the first expression is:

imperative = 'should';

What happens here is that Angular tries to put “‘should’” into a variable named “imperative” in the scope. “imperative” does not exist at this point so Angular creates it. Unlike JavaScript we did not have to declare “imperative” and when it is created it is only created in this scope. The next example is much more simple:

These two lines {{imperative}} look identical.

The full expression is only “{{imperative}}”. Every expression is evaluated and the last value that remains is what it is equal to. In this case that can only be “imperative” or its value “‘should’”. A more complicated example would be:

{{firstName = 'John'; lastName = 'Smith'; firstName + ' ' + lastName;}}

This again is an expression but you can see there are multiple steps and the steps are separated by a semi-colon. Here we create and assign firstName and lastName. The last steps is to put both of those values together to make the full name. The last step in an expression becomes it’s value so what would be left in the page is “John Smith”. The values are not limited to strings or numbers but objects {}, and lists [] as well. Through there is no control flow logic there is still logic in the form of truthy evaluation and ternary expressions.

{{valOne || valTwo || valThree}}

Returns the first truthy value in the set.

{{eatCookie = (whyNot) ? true : false}}

While this would be equivalent of setting eatCookie to whyNot

Scope

In all of this the scope is what ties the directives together. When an expression is evaluated it is run in and on the scope. When a scope is created as a child of an existing scope it can see all of the parents values. However adding new values to the scope will not add them to the parent. This controls the visibility of data in your apps.

A Note Before Moving On

All the included directives start with “ng-” to show that they are apart of the Angular namespace. This is done out of courtesy to anyone who would want to make their own directive, and if you do you sould prefix yours as well. This prevents two different versions of a Directive named “popup”. Instead we would have “my-popup” and “your-popup”. This is, as you will see, how Angular leads by example though promoting good practices.

The Most Basic Angular App

Getting an App running with Angular is fairly simple. Like all JavaScript libraries you will need to link to it with a script tag. After that add “ng-app” as an attribute to any tag besides head. Here, at the time of publishing, is a working example:

<!DOCTYPE html>
<html>
<head>
<script src="https://ajax.googleapis.com/ajax/libs/angularjs/1.2.14/angular.min.js"></script>
  <title>JS Bin</title>
</head>
<body ng-app ng-init="imperative = 'should';">
  These two lines should look identical.
  <br/>
  These two lines {{imperative}} look identical.
</body>
</html>

Live example: http://jsbin.com/xufal/latest/edit

That’s it! that is all. So the recipe for an Angular app is:

  1. A link to the library.
  2. An ng-app tag on a element in the page.

The attribute ng-app tells the library where the app will start. Here it is body but it could have been on the html tag. The thing to note is that what ever you want angular to be able to “see” needs to be either in the tag you placed ng-app on or a child element.

Next > Directives, Scope, and Expressions

Learning Angular.js

Angular.js is a powerful library that once you understand it, can be incredibly easy to work with. That is, once you know how to use it. However I believe that most of the struggle in learning Angular is in the presentation. So here I will walk you though the basics and lead up to the more powerful features of the framework. The goal is to build a solid foundation at each step along the way and with that footing build momentum as we go.

Overview

  • The Most Basic Angular App
  • Directives, Scope, and Expressions
  • Basic UI Directives
  • The World Revolves Around Lists
  • The Power of Templates
  • Controllers; The Real Power of Scope
  • Services; Sharing with controllers
  • Writing Filters
  • Writing a Directive
  • Using ng-view, or alt
  • Minification, Bootstraping, Lazy Loading and Other Fun

Now on to > The most basic Angular App

Top Down Angular.js

This last weekend I presented at Self.Conference in Detroit, MI what is the last version of my Angular.js talk. The talk has evolved along the lines of what I see as the most powerful and accessible features of Angular.js. So, if you have missed one of the talks here is what you should know to get started with Angular.js and a little of why it’s important. First, lets look at the most basic Angular.js app.

<html>
  <head>
    <script src="http://...link to angular..."></script>
  </head>
  <body ng-app>
  </body>
</html>

All you’ll need is a link to Angular and the ng-app tag in your page. To see a working example look here.

Decoupling the UI

Web pages have been forever HTML and JavaScript, since 1996 and for as long as anyone can see into the future; even if some only see it as ASM.js. The markup would show that the page could look like but it is the JavaScript that creates the tab views, carousels, and popups that are ever present in web design. Add in two way data binding and at best this connection has been murky, and it rarely scaled well. The goal then should be to have the markup describe the content of the page and go just far enough to show where the data will affect it. This would remove or decouple the View that the user sees from the code that controls it.

Web Components

This description of markup and interaction can be seen in the button or form tag. Though as there are a near infinite number of ways to want to interact with the page it would not make sense to put everything in the standard. The way to do this is though web components. Each one wraps up a feature that binds to some data. This is the idea behind Angular.js Directives. The annotate the markup with new features, and bind to data that will update the UI automatically. Web components will be in the spec after HTML5 and Google’s Polymer Project provide a “Polyfill” as it emerges.

“Expressive” View Data Glue

Angular uses {{Expressions}} to connect it’s components to data. So when you use a ng-model on an input and then show that value in the page with {{name}}, if you know it or not your using expressions.

<input ng-model="name"/>
<br/>
<span>Hello: {{name}}.</span>

Here you can see the “annotation” of our directives. We take an input and assign it to name and then we bind that value the page with the double curly braces “{{” and “}}”. It’s easy to see that “{{name}}” is an expression if even a short one but the value provided to ng-model is also an expression. Expression are unique in that they are not JavaScript and though they are powerful they are not really anything more than a basic glue to firm up your Directives in your View. The real work is done in controllers.

To learn more about Directives and Expressions check out these (soon to be published) posts.

Filling the views with Controllers

Controllers are what bind the data, where ever it may come from or what ever it may be to your views. Controllers can take many parts and provide just what you need to the scope of your view. This helps reduce the complication of the views. A clean controller will not be very complicated either. Their power is being able to have other resources injected into the scope of your page and they are bound to the page though their own directive. Take the very simple example:

<script>
  function CountController($scope) {
    $scope.total = 0;
    $scope.AddOneClicked = function () {
      $scope.total++;
    };
  }
</script>
<div ng-controller="CountController">
  <button ng-click="AddOneClicked()">Add One</button>
  <br/>
  <span>Count: {{total}}.</span>
</div>

Controllers are what orchestrate MVC, to the point where it seems better to describe it as View / Controller / Data frameworks. With this functionality Angular does not stop here but continues to encourage good development practices with the other features in its framework.
To learn more about controllers in detail check out this (soon to be published) post.

Building a full application

All of the features of Angular shown so far are very functional on their own but how do they work in scale? Well Angular is build around this idea. As our page grows and we continue to add controllers they should be organized into a module as any JavaScript should. Angular provides it’s own module wrapper for your app. With it you can organize your controllers and other code. You can even break your code into smaller modules that focus on a specific feature, and use it as a dependency for your app. If the feature is distinct enough then you may want to make it a directive, and as a module it’s already setup as a package. The rest of the Angular.js architecture is based around development patterns like this. Modular design and encouraging decoupling. This can be seen though they way Angular uses injection. Angular has been built around testing and though updating what gets injected the same controllers that were use by your view can now be tested in any number of frameworks. Beyond this there are a host of other components and features in Angular to build out Single Page Web Apps and provide wrappers for RESTful data endpoints. Almost every part of the frameworks is extendable as well, so once you get your feat wet there is no limit to what you can do, and sometimes shouldn’t ;-).
To learn more about extending Angular. in detail, check out these (soon to be published) posts.

Summary

Angular is a framework that someone on any level of web or programming experience can start to benefit from. It’s designed to enable the people who use it and promote good development practices along the way. The basic concepts of Angular are the same concepts that are being developed for the next set of web standards, and will remain relevant when they are eventually supported. Though these examples are extremely simple they underscore how little one needs to get started with Angular.

Simple Express.js. Setup, Plus Routes.

I’ve dabbled in Node.js here and there but recently I dove head in head first to work on a personal project. When getting started with Express it was easy to find examples that had much more than what I needed. Taking it all in this is how it boils down.

A Static Server

It’s easy to setup a static web server in Express. Yes, you can use the Node.js and just the “http” library to do the same thing, but Express actually depends on that lib so technically you are… This setup is a building block for the foundation of you server.

//Include and return an express object
var express = require('express');
var app = express();

//Setup a static web server
app.use(express.static(__dirname + '/'));
app.listen(3000);

It much more typical for a site not to be entirely static. In application the static directory would not be your root folder but a sub like ‘/public’ or ‘/assets’

app.use(express.static(__dirname + '/public'));
//or
app.use(express.static(__dirname + '/assets'));

Modules

Most of the additional code in the ‘app.js’ is there to setup modules. Modules add functionality to the express stack. The static routing we just saw is one example. ‘express.static’ is a function that returns a module that is set to return files from the directory you defined. Modules are added to express through ‘app.use’. After you have added a module it will be applied to every request. Some examples are bodyParser, compression, router, or passport. A mock for a module would look like this.

var module = function (req, res, next) {
  //req -> request, res -> response,
  //next -> callas the next module in the data pipe
  console.log('This module works!');
  next();
}

app.use(module);

Modules get every request and can modify it, push data into the response object, or update locally scoped values. After a module finishes it’s work it must call ‘next()’ to get move on to the next module. Modules are very powerful. Though, unless your looking to change the fundamental behavior or features of the server the better choice for general dynamic content, like MVC or REST, would be to use the router module instead of writing your own.

Routing – Foundation of MVC and REST

Though the ‘router’ module you can address specific requests with a handler function. For MVC you map a route to the controller, a.k.a. your function. REST works the same way. The ‘router’ allows you to map to your function handlers by the http request verb that was used. So you can respond to ‘GET’, ‘POST’, ‘PUT’, ‘Delete’, or any other verb you client makes up. If you map it, express will respond to it.

app.all('/chat/', hndlr);        //All request
app.get('/posts/:id?', hndlr);   //Only GET
app.post('/posts/', hndlr);      //POST
app.put('/posts/:id', hndlr);    //PUT
app.delete('/posts/:id', hndlr); //DELETE
}

Notice how we provide a path or route to filter our responses? Each time we call ‘app.verb’ it is appending the handler a list that is applied to a request. The first rout to match the request will have its function called so order matters. A mock for a request handler looks like this

var module = function (req, res, err) {
  //req -> request, res -> response,
  //err -> if you including errors
  console.log('This rout is', res.route);
}

With that you should be off and running.

Rethinking Single Loop Optimization to Enable Modular Design

It’s not uncommon to hear that you can make a program more efficient by combining loops. The idea is “why loop over something three times when you can loop over it once?”. However there is danger in this idea as a blanket assumption. Furthermore it impedes patterns that can be quite scalable and powerful.

//Setup
var l = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
function funcOne(i) { /*...*/ }
function funcTwo(i) { /*...*/ }
function funcThree(i) { /*...*/ }

//First way
_.each(l, funcOne);
_.each(l, funcTwo);
_.each(l, funcThree);

//"Optimized" way
_.each(l, function (i) {
  funcOne(i);
  funcTwo(i);
  funcThree(i);
});

When This Assumption is Correct

The more I though about this the harder this statement became to justify. In an academically absolute circumstance each loop creates some over head. So, in that case it is correct to cluster the operations on each item. In cases when the list or collection that you will loop over is extremely large that overhead could be crippling. The classic example is reading a very large file from disk. Keeping the data in memory was problematic in the past. However now modern programming patterns have reduced this problem or removed it all together by using streams and iterators.

Thinking Modular

If we let go of the first assumption and look at this another way we can lay the foundation for some very powerful patterns. So lets look again at our first example and make a minor logical jump.

//If the "Optimized" way
_.each(l, function (i) {
  funcOne(i);
  funcTwo(i);
  funcThree(i);
});
//Is equivalent to 
//First way
_.each(l, funcOne);
_.each(l, funcTwo);
_.each(l, funcThree);
//What would the benefit be instead of working on one element
//in the set the function took the set instead?
funcOne(l);
funcTwo(l);
funcThree(l);

The power from this assumption is that if the function takes a set instead of just an element from it each function now entirely wraps a step or possibly a feature. The other advantage to this is that you could store your steps in their own set or collection that you could programmatic add and remove items. This is how Express in Node.js works. Every time you add a module it gets added to a list. When a request comes into the server it walks down the chain of modules with each one processing data is it goes. This is very powerful architecturally.

//A list of modules
var m = [modOne, modTwo, modThree];
//We can now just iterate over our modules 
_.each(m, function (f) { f(l); });

Getting the path of a script file during execution

Recently I was looking at a script in an Angular.js controller that used a template. An absolute path was being used to reference the template from the controller in each as this was the way the pattern we were using for modules. Though it seemed like a good way to isolate concerns and organize the code having hard coded strings always bothers me. So I started looking into if it was possible in JavaScript to get the file location of a script during execution. As it turns out there are a couple of ways and here is how I ended up at my solution.

arguments.callee()

There were some suggestions that you could build a call stack with arguments.callee() by getting the function that was scoped and calling .toString() to get its name. First off this requires access to the whole call stack and secondly in ‘strict mode’ it is no longer allowed. So this was not really ever an option for me.

document script tag inspection

The second approach I found that was popular was in a script to inspect the DOM and get the “src” attribute of the last script tag. The assumption is that since the scripts are parsed in order that as the code was executed that it would be the current and last script in the document before the next was added and run.

//Select the "last" script tag, the one that currently being interpreted
//at least that's the assumption.
$('script[src]').last();

The problem with this approach was that it was based on alot of assumptions. It also would not work with lazy loading or any script tag with an async attribute. Lastly, if we are going to be picky it would be ideal if we could programmatically call and return the path of the file we are in at any time.

Inspecting the call-stack of an exception

This method was the most reliable of the three if not the least convenient to extract the final information from. This method works on try / catch / throw in JavaScript and the Error() object. By creating and throwing an error the exception can then be caught and the location of the file that caused it inspected from the call stack. This can also be done at any time during script loading and as many times as one would need/want. The specifics are commented in the code and the full reference can be found in the project it is apart of on my GitHub account.

    function ScriptPath() {
      var scriptPath = '';
      try {
        //Throw an error to generate a stack trace
        throw new Error();
      }
      catch(e) {
        //Split the stack trace into each line
        var stackLines = e.stack.split('n');
        var callerIndex = 0;
        //Now walk though each line until we find a path reference
        for(var i in stackLines){
          if(!stackLines[i].match(/http[s]?:///)) continue;
          //We skipped all the lines with out an http so we now have a script reference
          //This one is the class constructor, the next is the getScriptPath() call
          //The one after that is the user code requesting the path info (so offset by 2)
          callerIndex = Number(i) + 2;
          break;
        }
        //Now parse the string for each section we want to return
        pathParts = stackLines[callerIndex].match(/((http[s]?://.+/)([^/]+.js)):/);
      }

      this.fullPath = function() {
        return pathParts[1];
      };

      this.path = function() {
        return pathParts[2];
      };

      this.file = function() {
        return pathParts[3];
      };

      this.fileNoExt = function() {
        var parts = this.file().split('.');
        parts.length = parts.length != 1 ? parts.length - 1 : 1;
        return parts.join('.');
      };
    }

Angualr.js $apply, $digest, Thread Blocking and Preemption

It’s been a week since I gave a talk about Angular.js and someone mentioned the importance of not calling $apply during a $digest cycle. I have read this too, but it struck me at the time that this could even be possible given that script execution in the browser is single threaded. This single threaded-ness is also the principle behind Node.js and it’s asynchronous architecture. So I decided to follow up on my own.

The Browser Update Cycle

A browser splits it time between two phases. The first is rendering the page by reading the markup and applying styles. The second is to execute any scripts that have been queued to run. Then it renders any changes to the page and executes the next script that has been queued. This is actually where the practice of using

setTimeout(fn(), 0)

to allow UI updates comes from. This creates a time out with no delay and fn() is pushed on the end of the script queue. Once the current script scope, the entirety of the call stack, is finished the script engine yields to the render cycle and in the next script cycle fn() is called. If you use Underscore.js (_) the short hand function is _.defer(fn()). Node.js does the same thing though with out the render cycle and because all interaction outside of the main thread is pushed you callbacks the process never waits, and efficiently processes the next function that was queued.

Thread Blocking and Preemption

The rules for execution is that the queue takes functions and each function is executed to its completion. In this process there is no preemption in the execution of code. No matter how deep the call stack may be when a time out or event fires it is put on the end of the script queue and serviced in order of arrival. In this way a complex or poorly written loop can block the execution of the code that is in the queue, and essentially blocks execution.

The issue with $apply and $digest

So with the theory of what we know, how is it possible to call an $apply during a $digest? Angular has it’s own event loop, and one of the things it does is observes any changes to the data in the $apply cycle. This happens automatically for models that are updated inside controllers, scopes, or ng- events, and manually by calling $apply directly. The next step is for angular to call $digest to apply these changes to the scope. Now from what know $apply can’t preempt or interrupt the execution of $digest so what cause the error. The issue is that Angular knows that $digest has been put on the process queue and that calling $apply will interfere with cycle. Angular tracks this by setting the $$phase in the root scope.

The Proof

Theory is sound but I feel better when I have examples that prove it. So I created two examples to illustrate the point of blocking and the absence of preemption.

Blocking Code

This code shows that the interval wont fire until it has a chance to execute after the current block of code has finished. It is interesting to note that not only do only just one of the intervals fire but if the clearInterval() is called in the first code block and not from a timeout the interval never gets a chance to fire at all.

console.clear();
function blockingLoop (delay) {
  var start = new Date();
  while((new Date() - start) <= delay){
    // noprotect
    // ^^^^^^^^^ this stops jsbin from exiting the loop.
    // if you modify this, beware!
  }
  //This will show up formatted on a native console
  console.log('Delayed for %sms', (new Date()) - start);
}

var delay = 500;
var numberOfIntervals = 4;

var intervalId = setInterval(function () {
  console.log('Interval Called');
}, delay / numberOfIntervals);

blockingLoop(delay);

//We expect to see "numberOfIntervals" notifications
//But we only get one, since is executed after the script block

//If you call "clearInterval" outside of this time out the
//interval will never be called...
setTimeout(function () {clearInterval(intervalId);}, 0);

Live Example

No Preemption

This example shows that no matter where the time out is set that they will not execute until after the current code block and call stack is finished. The timeouts also execute in order of their placement in the queue, as any proper queue should function. :p

/*
  To use press run in the console window
*/
console.clear();
console.log('--- Start Script Scope ---');
var timeoutId = 0,
    theTimeout = function (id) {
      /*
        We return a function with the id in a closure
        so that we can assign a number to it and see
        the order in which they were called
      */
      return function () {
        console.log('--- Callback ' + id + ' Called ---');
      };
    },
    one = function () {
      console.log('enter one -->');
      two();
      console.log('exit one <--');
    },
    two = function () {
      console.log('enter two -->');
      three();
      console.log('exit two <--');
    },
    three = function () {
      console.log('enter three -->');
      //Set the time out to zero so it will be next on the queue
      setTimeout(theTimeout(++timeoutId), 0);
      console.log('exit three <--');
    };

console.log('Call Function Chain');
one();

console.log('Call Function Chain Again');
one();

console.log('--- End of Script Scope ---');

Live Example

Hitting the Ground Running with Angular.js

I recently gave a talk on Angular.js and the fundamentals of how it works. My hope was to provide many examples of how to use directives to annotate the markup of the page and explain the subtleties of what was going on along the way. The group was very knowledgeable and we had a great discussion though out. Here are the the links that came along with the slides.

TypeScript and My Fat Arrow Folly

I recently started working in TypeScript. It was really easy to pick it up, because if you know JavaScript, then you know TypeScript. So it was not long before I was converting all of my old helper code into TypeScript as well. However I ran into a problem with the string formatter I had writen for JavaScript. It seemed easy enough but despite everything I tried, the code would not compile. This is where I started:

interface String {
    showString: () => string;
}

String.prototype.format = () : string {
    var formatted = this;
    for (var i = 0; i < arguments.length; i++) {
        formatted = formatted.replace(
            RegExp("\{" + i + "\}", 'g'), arguments[i].toString());
    }
    return formatted;
}; 

Yet no matter what I tried I could not get it to work. Every time I would get an error stating “_this is not defined…”. The issue ends up to be very simple so let’s start at the top with “this”. In JavaScript a function references the scope that it executes in with “this”. That usually means the instance of the object the function is called in, or it means the window when not encapsulated. This can can also be changed by calling a function with f.call() or f.apply(). It can take some understanding to know what “this” actually represents in the context so in TypeScript functions were given a fat arrow syntax to have them perform like functions in C, Java, and C#.

Take a look at:

var f = function (postFix) {return this + postFix};

To add TypeScript syntax you would define types

var f = function (postFix: string): string {return this + postFix};

In both of these cases this refers to the scope of the function just like classic JavaScript. However, things change when we do this…

var f = (postFix: string): string {return this + postFix};
//or more correctly
var f = (postFix: string): string => {return this + postFix};

When you remove the function from in front of the parameters then it is no longer a classic function. It becomes a “Fat Arrow” function, apparently even with out using the “=>” syntax. In the examples above “this” now refers to the class that the function exists in like in C#.

In my attempt to assign a function to the prototype of string I omitted the function keyword so it was interpreted as a “Fat Arrow” function and tries to bind this to the scope of the class. However the function dose not exist in a class and causes the error “_this is not defined”.

When I add the “function” keyword, the function is interpreted as I intended and works correctly.

interface String {
    format: () => string;
}

String.prototype.format = function () : string {
    var formatted = this;
    for (var i = 0; i < arguments.length; i++) {
        formatted = formatted.replace(
            RegExp("\{" + i + "\}", 'g'), arguments[i].toString());
    }
    return formatted;
};