Home » rss news & blogs » sources

dave

Syndicate content
Your blog is probably better than mine.
URL: http://thesmithfam.org/blog
Updated: 56 min 38 sec ago

Communication Between Directives in AngularJS

Mon, 2012-12-17 23:11 -
img { box-shadow: 0 0 10px #aaa; border: 1px solid #999; border-radius: 5px; padding: 10px !important; } tt { background: #f4f4ff !important; padding: 2px 4px !important; border: 1px solid #e6e6ff !important; border-radius: 4px !important; } .syntaxhighlighter table td.code .container { padding: 5px !important; }

Warning: This article is long and thorough. If you’re in a hurry, you can skip straight to the final product here:

http://plnkr.co/edit/6KxHY8ZpE83Z2PeNWlYi?p=preview

Prerequisites to this article

Before reading this, get to know these AngularJS terms. You don’t need too much depth, but you need to know what they are:

You should also peruse the Angular Developer Guide, but don’t feel bad if a lot of the jargon does not make much sense at first.

Step 0: Roadmap

We’re going to create two custom directives that communicate with each other. We’ll really dig deep into the first directive, explaining every line of code as we go.

Then we’ll glue the directive to a controller via a scope object.

Lastly, we’ll create a second directive and glue it all together.

Step 1: A basic directive, dissected

For this example, we’ll create a custom search box that can be placed in our app with a custom <my-search-box> element. This directive causes Angular to convert <my-search-box> in your HTML into <span>My Custom Search Box</span>. This is not useful yet, but it will become immensely useful as we grow this concept in a few paragraphs.

We’ll create a file called “app.js” with this content:

angular.module("MyApp", []). directive('mySearchBox', function() { return { restrict: 'E', replace: true, template: '<span>My Custom Search Box</span>' }; });

Let’s walk through each line of that directive:

angular.module("MyApp", []).

This line declares a new module called “MyApp”. The empty array to the right can contain the names of other modules on which this module depends (this is where you would put AngularUI modules for example if you want to use AngularUI). In this case, this module happens to be our “main” application module, but Angular really doesn’t know that from this line of code. That happens in the HTML with <html ng-app="MyApp">. Also, you only declare your main application module once, even if you have many directives. There are ways to look up your module if your code spans multiple files, or you can just create a global variable to reference your module and use that when building your directive.

directive('mySearchBox', function() {

Here we are declaring a new directive. Notice that we camel case the directive name. When Angular encounters <my-search-box> in the HTML, it will normalize that into “mySearchBox” to look up the directive. Thus, “mySearchBox” is called the “normalized” name.

return {

Angular expects the directive function to return an object with properties that describe the directive.

restrict: 'E',

This tells Angular that “my-search-box” must be an element. Angular directives can also exist as HTML attributes, HTML class names, and even HTML comments (!). It’s okay if this doesn’t make sense yet.

replace: true,

This tells Angular to fully replace <my-search-box> with the directive’s template HTML. Alternatively, Angular can add the directive’s template HTML to the <my-search-box> element as a child element. For our example, we want Angular to fully replace <my-search-box> because <my-search-box> is not a valid HTML element name. You can imagine wanting Angular to simply augment an element with child elements in some scenarios, but not this example. We’re effectively creating a “widget” that can be instantiated and reused in our HTML.

template: '<span>My Custom Search Box</span>'

This is the directive’s HTML template that will be rendered by the browser. I don’t recommend using hard-coded template strings in your directives like I’ve done here. I do it this way to make the example clear. Normally, I use the templateUrl property and serve the HTML as a “partial” from my web server. Angular caches these partials, and you can even pre-load them when your app loads. This way, I can use server-side template technologies for things like localization. Although, for the best performance, I recommend that you serve these partials statically from a CDN or other fast caching service.

Now we can use this directive in our HTML like this:

<html ng-app="MyApp"> <head> <script src="http://ajax.googleapis.com/ajax/libs/angularjs/1.0.3/angular.min.js"></script> <script src="app.js"></script> </head> <body> <my-search-box></my-search-box> </body> </html>

When you visit that page in your browser, you’ll see “My Custom Search Box” if all went well above.

So far this is a pretty useless directive, but we’are about to take it to the next level.

Step 2: Giving your directive its own scope

Each instance of a directive has its own scope. And of course, the scope is a child of the enclosing scope where you instantiated the directive in the HTML. For example, if your directive exists inside a <div ng-controller="MyController">, then your directive’s scope will be a child of MyController‘s $scope.

For example, the following HTML uses two <my-search-box> elements. Angular gives each <my-search-box> its own independent scope:

<body> <my-search-box></my-search-box> <my-search-box></my-search-box> </body>

Let’s define our directive’s interface to the outside world using the scope property. Our interface will have two values: searchText and isSearching. We will use searchText to store the user’s search text that they enter into an <input> box, and we’ll use isSearching to tell the directive when a search is in progress.

angular.module("MyApp", []). directive('mySearchBox', function() { return { restrict: 'E', replace: true, scope: { searchText: '=', isSearching: '=' }, template: '<span>My Custom Search Box</span>' }; });

Did you see the scope = {...} property above? That defines the public elements of this directive’s scope. Notice how we used '='? That tells Angular that we want a scope variable to have two way binding to the outside world. This is part of the directive’s HTML interface. This allows callers to use our directive like this:

<my-search-box search-text="someScopeVariable" is-searching="someOtherScopeVariable"> </my-search-box>

In other words, the directive allows outside callers to bind their own scope variables to this directive’s searchText and isSearching variables. This is how you communicate with the directive from the outside world.

The variables someScopeVariable and someOtherScopeVariable come from the enclosing scope, which usually is managed by a controller outside the directive. If, for example, we had <div ng-controller="MyController"> enclosing <my-search-box>, then someScopeVariable and someOtherScopeVariable would be managed by MyController.

In the code above, the search-text gets normalized into searchText in the directive’s scope. Likewise, is-searching becomes isSearching.

When we assign search-text="someScopeVariable", we are telling Angular to bind this directive’s searchText scope variable to a scope variable from the enclosing scope called someScopeVariable. Any time the enclosing scope’s someScopeVariable changes, the directive’s scope variable searchText will also change. And it works in the other direction too. Any time the directive changes its searchText variable, Angular will automatically change the enclosing scope’s someScopeVariable to match.

These scope variables are useless unless we also make them visible somehow, so let’s modify our template HTML to use them. While we’re at it, let’s make this actually look like a search box instead of a simple piece of text:

angular.module("MyApp", []). directive('mySearchBox', function() { return { restrict: 'E', scope: { searchText: '=', isSearching: '=' }, controller: function($scope) { $scope.localSearchText = ''; $scope.clearSearch = function() { $scope.searchText = ""; $scope.localSearchText = ""; }; $scope.doSearch = function() { $scope.searchText = $scope.localSearchText; }; }, replace: true, template: '<form>' + '<div>' + '<input ng-model="localSearchText" type="text" />' + '</div>' + '<div>' + '<button ng-click="clearSearch()" class="btn btn-small">Clear</button>' + '<button ng-click="doSearch()" class="btn btn-small">Search</button>' + '</div> ' + '<div ng-show="isSearching">' + '<img ng-show="isSearching" src="http://loadinggif.com/images/image-selection/3.gif" /> ' + 'Searching...' + '</div>' + '</form>' }; })

Remember, I suggest you use templateUrl instead of template when your HTML starts to grow like this.

Now we have a search box form that lets the user enter some search terms, which we store in the directive’s scope as localSearchText. Notice that we didn’t put localSearchText in the scope: {…} definition, because it needs no external binding. In other words, this is a “private” scope variable that the directive uses to store the human text input until we are ready to actually do the search. This is because we don’t want every single keystroke to initiate a search. Only when the user clicks the “Search” button.

Notice also that we added a controller with controller: function($scope) {...}. This code defines a typical controller so our directive can take action in response to user input, like button clicks with ng-click.

This HTML also provides a “Clear” button to zero out the search box and a spinner to show when the search is in progress. The directive relies on outside callers to tell it when a search is in progress by setting the isSearching variable to a “truthy” value.

After making these changes to app.js, our page should look like this:

Now that directive is finished. Notice it doesn’t do much. It requires an outsider to stimulate it into action.

Step 3: Creating a Controller

Let’s create a controller that communicates with the directive we wrote. This isn’t strictly required to allow two directives to communicate, but in most cases it will be necessary because someone has to glue them together with the business logic specific to your application. This is a job well suited to an Angular controller.

Let’s make a simulated city search that allows the user to search for cities. Because it’s an example, the search will always return the same results.

<div ng-controller="CitySearchController"> <h1>Search for Cities</h1> <my-search-box search-text="citySearchText" is-searching="isSearchingForCities"></my-search-box> </div>

And the accompanying controller, which I placed in app.js:

function CitySearchController($scope, $timeout) { $scope.$watch("citySearchText", function(citySearchText) { $scope.citySearchResults = []; if (citySearchText) { $scope.isSearchingForCities = true; $timeout(function() { // simulated search that always gives the same results $scope.isSearchingForCities = false; $scope.citySearchResults = ['New York', 'London', 'Paris', 'Moab']; }, 1000); } else { $scope.isSearchingForCities = false; } }); }

This controller’s $scope.citySearchText and $scope.isSearchingForCities variables are bound to the directive’s scope variables searchText and isSearching because of the HTML attributes that we specified on <my-search-box>.

This controller is pretty basic, so I won’t describe every line of code. All it does is $watch() for changes to citySearchText and get some fake search results with Angular’s $timeout service.

Because of Angular’s excellent isolation-centric design, this controller would be very easy to write unit tests for, but that’s another article.

When you visit the page, you should now see a search box. If you enter some text into the input box and click “Search”, you’ll see a spinner for 1 second, which then disappears:

Step 4: Finally add a second directive

Now we’re ready to add another directive. For this example, we’ll create a search results directive. This directive has almost the same public interface (i.e., scope) as the <my-search-box> directive, with one extra variable: the actual search results that caller wants to display.

It looks like this:

directive('mySearchResults', function() { return { restrict: 'E', transclude: true, scope: { isSearching: '=', searchResults: '=', searchText: '=' }, replace: true, template: '<div ng-hide="isSearching">' + '<h4 ng-show="searchResults">Found {{searchResults.length}} Search Results For "{{searchText}}":</h4>' + '<ul ng-show="searchResults">' + '<li ng-repeat="searchResult in searchResults">' + '{{searchResult}}' + '</li>' + '</ul>' + '</div>' }; });

Everything should look familiar from your study of the first directive. There are no new concepts here. Let’s use our directive in our HTML:

<div ng-controller="CitySearchController" style="margin: 20px"> <h1>Search for Cities</h1> <my-search-box search-text="citySearchText" is-searching="isSearchingForCities"></my-search-box> <my-search-results is-searching="isSearchingForCities" search-results="citySearchResults" search-text="citySearchText"></my-search-results> </div>

Now your page should show some search results after clicking the “Search” button and waiting for 1 second:

Just to prove that there is indeed zero coupling between the two directives and the controller, I added a second controller and a second instance of each directive to search for fruits, which you can see in the plunk below.

The Finished Product

Here it is: http://plnkr.co/edit/6KxHY8ZpE83Z2PeNWlYi?p=preview

Conclusion

From the sheer length of this article, you may think that this is complicated, but the reality is that it only took me about 30 minutes to whip together the working example in the plunk.

Main points I hope you took from this article:

  • Directives are easy to create.
  • Directives have their own scope
  • Directives can communicate with the outside world via HTML attributes
  • Directives encourage loose coupling
  • Directives encourage reuse and UI consistency
  • Directives are easy to test (well, this is a future article)
  • Controllers can use directives with zero coupling
  • The Prime Directive has nothing to do with AngularJS (bummer)

AngularJS is too humble to say you’re doing it wrong

Sun, 2012-12-02 23:12 -

For years, web application developers have used DOM manipulation tools like jQuery to control their user interface. Astute developers have taken it to the next level with client-side templating tools like Mustache and Handlebars.js to build sophisticated user interfaces on the client side.

And then AngularJS came along.

And we all realized we’ve been doing it wrong.

Way wrong.

The Old Way

Remember before you discovered AngularJS? Back when your code was organized like this:

  1. HTML that defines your page
  2. JavaScript that downloads AJAX data
  3. HTML that defines a client side template
    (yeah, this: <script type="text/html">...</script>)
  4. JavaScript that renders the client-side template
  5. JavaScript that injects the rendered template HTML into the DOM

You thought that was pretty cool. “Hey look,” you said, “I’ve off-loaded template rendering to the browser!”. Yeah, you were pretty cool.

But then AngularJS showed you how you were wrong. You could accomplish the same client-side magic with a lot less code.

The New Way

Under AngularJS, your code can be organized like this:

  1. HTML that defines your page and client-side templates inline
  2. JavaScript that downloads AJAX data

How does that even work? I mean, you’ve got like less than half of the bullet points now.

The answer: Data Binding.

Data Binding is the secret sauce of AngularJS (along with a couple dozen other delicious spices and condiments). Oh, and it’s not a secret at all. The code is actually pretty easy to read, despite being pure magic awesomeness on environmentally-friendly steroids.

Shall We Do Show-and-Tell? The old way

This should be very familiar. You’ve got an HTML page, and you want to add some dynamic content with a client-side template:

Here’s the page HTML:

<html> <body> <div id="my-list-of-animals"> </div> </body> </html>

Let’s use Handlebars for the client-side template:

<script id="animal-template" type="text/x-handlebars-template"> <div> <div>{{animalName}}</div> <div>{{favoriteFood}}</div> </div> </script>

And you need some JavaScript to download the AJAX data, render the client side template, and inject it into the DOM:

$.get("/api/animals/", function(response) { var source = $("#animal-template").html(); var template = Handlebars.compile(source); $.each(response, function() { var html = template(this); $("#my-list-of-animals").append(html); }); });

Put all that together somehow, and wow, that’s a lot of code to do something that should be very simple.

That covers all 5 bullet points above. You’re still cool, right?

The AngularJS Way

Remember how there are only two bullet points. Well, here they are:

First, your page HTML:

<html ng-app> <body> <div ng-controller="MyAnimalController"> <div ng-repeat="animal in animals"> <div>{{animal.animalName}}</div> <div>{{animal.favoriteFood}}</div> </div> </div> </body> </html>

Did you see that? There’s no <script> hack. The template is right inside the page! Right there. In-line. Right where you wanted it all along, but never had the guts to ask. But I digress.

Second, the JavaScript:

function MyAnimalController($scope, $http) { $http.get("/api/animals/").success(function(response) { $scope.animals = response; }); }

And that’s it. It really is glorious. The AngularJS team really distilled the client-side template problem to its essence and produced an elegant solution. But don’t take my word for it. Check out the win list below.

Win List

Look at all the prizes you won by using AngularJS:

  1. CSS classes are just for CSS now.
    You used to abuse the HTML class attribute so you could find elements in the DOM with jQuery. Now, your class attributes are only for CSS. You don’t have to wonder anymore whether a particular class is used by JavaScript or CSS. The answer is always CSS: The way nature intended
  2. No <script> hacks.
    You don’t have to trick the browser into ignoring your client-side templates anymore. Don’t you feel cleaner?
  3. Client side templates are cohesive with your page
    You used to have a pile of client-side template files scattered throughout your project, or all crammed into your HTML <head>. Now they are right in the page, exactly where you wanted to read them in the first place.
  4. You don’t have to name every template
    You used to name each <script> element with an “id” attribute to make it findable by jQuery. You can nuke those strings in your JavaScript and HTML, and not worry about them getting out-of-sync.
  5. You have control over the scope of your JavaScript
    Previously you had to worry about your jQuery selectors casting too wide a net and selecting elements beyond what you intended. For example, suppose there happened to be an element in the page somewhere with class “animal”, and you didn’t know about it. Then you wrote a jQuery selector like $(“.animal”). Boom, you just mofidied an element you didn’t intend to. With AngularJS, your JavaScript cannot reach outside the ng-controller demarkation.
  6. You don’t have to remember to clean up HTML on refresh
    Let’s say I want to refresh the animal list in this example. Under jQuery, I have to remember to do this: $("#my-list-of-animals").html("") before I start .append()ing new animals. In AngularJS, I just replace $scope.animals with the newly downloaded list, and it automatically clears out the old HTML.
  7. Your JavaScript is cleaner
    Your JavaScript has no CSS selectors anymore. It used to be littered with strings to locate elemenents in the DOM. Now it’s just got business logic. Pure, sweet business logic.
  8. You can unit test your JavaScript without a DOM
    I should have mentioned this first. Notice how my JavaScript has no knowledge of a DOM? It doesn’t even know there’s HTML involved at all. This makes it much easier to unit test, because you don’t need to load a big chunk of fixture HTML to test your JavaScript. AngularJS provides some great docs on testing too.
Almost Too Humble

I started reading about AngularJS and re-working parts of my projects to use it in earnest only a few weeks ago. A day into the effort, the light bulb went on for me:

I’ve been doing this all wrong

At that point, I started to wonder why the AngularJS team didn’t write article after article with the same title: “You’re Doing It Wrong”. And that’s what inspired me to write this.

So there you have it. An opinionated blog post about an opinionated framework.