Eric Terpstra

One more thing…

I took the liberty of making a custom directive out of the Twitter Bootstrap Carousel widget. You’ll see it in partials/catDeatil.html as . I’m not 100% certain I’m doing things the ‘correct angular way’, but it seems to work.

Demo | Code

The catCarousel.html partial:

The directive code:

The templateURL property specifies the HTML to insert into the directive tag. I’ve restricted the type of directive to an element name. It’s just easy that way. One caveat though, it that special considerations need to be made for this to be IE7/8 compatable.

The link function will take the value of the ‘pics’ attribute in the catcarousel HTML tag and assign it to the directive scope. Whenever the ‘cat’ object changes – either by clicking Next/Prev, or selecting a cat from the grid – the directive will update the ‘pics’ and call the carousel() function on the root element of the directive template.

And that just about wraps it up. There’s plenty more code in the cat apps than outlined in these blog posts, so if anyone is interested, please take a look at the project on GitHub. I tried to add as many useful comments as I could. If any Angular experts run across this and are horrified by any of the code, please let me know! Thanks. Bye.

Demo | Code

During the creation of Angular Cats!, it didn’t take me long to realize that I was straying from best practices and the intentions of Angular’s creators. I dug myself a bit of technical debt in the name of expediency, and have now come to pay the piper. Over the past few days I’ve been refactoring major portions of the app, and wound up with almost an entirely new codebase. Large sections are still intact (e.g. the translator service), and functionality is basically the same, but a few key differences are present.

The largest change by far is the ability to deep link. Every cat has its own URL, and can be bookmarked.

To get the deep-link ball rolling, the following code was added to app.js:

The routes allow a user to go to a specific ‘page’ of cats in the cat list, or navigate to the details of any given cat – provided you know its ID. I also store the page number in the URL of the cat detail page so the user can navigate back to the page previously viewed when clicking ‘Back’ on the cat detail page.

In order to navigate around the application, the controllers now use the $location module, and will change the path according to the behavior of the user. The code below shows how the handler for clicking a cat to view details has changed.

Before (use events to change state):

After (use location to change state):

The CatsService module was completely overhauled to include a getCat() method in addition to getCats(), along with a few other useful methods. Oh, and this version actually has the ability to contact the live Petfinder.com API! Using a config constant, the app can switch between grabbing cat data from a .json file on disk, or reaching out to the live Petfinder API (via a PHP proxy on my own server). While building the app, I usually relied on a static json file for data, but it’s nice to be able to contact a live service to return fresh data.

The returned data is also stored in the CatService module. This data is basically the catCollection property that I previously stuck in $rootScope. Storing application data and state information on $rootScope just didn’t seem right, so I created some properties and accessor methods (get/set) on CatService, and used that instead. Worked out quite nicely.

Below is the new CatService module. Notice that it’s quite a bit larger that the previous module. This time around, the service had a few private variables and functions that the service uses for itself, and the CatService object is returned by the factory and injected into the controllers. The properties of the CatService object are exposed to the controllers and can be used wherever CatService is injected.

The first major feature of this updated service is the remoteSvc resource. Instead of just grabbing a .json file from disk, it will contact the proxy.php service and grab live data returned from the Petfinder API. The query object passed into the $resource function demonstrates how to override default $resource methods. This really isn’t necessary in my case, but I did it just for kicks.

The line var service = (ENDPOINT === "LOCAL") ? localSvc : remoteSvc; will look at the ‘ENDPOINT’ constant set in the application config (see app.js), and determine whether to use the local json file, or server resource to gather the cat data. It’s a quick and dirty approach, and in a larger system it would be better to abstract this into a proper config file, with two separate service modules, but it works pretty well for a small app with one or two services.

The CatService object has some getters and setters for accessing the selected cat, and the selected cat’s index value in the cat collection array. And, of course, there are the getCats and getCat methods, which gather the necessary data for the list and detail views (respectively).

Continued from: Angular Cats! Part 2
Full Source Code: GitHub: jsCats/ngCatsHOM

In part 2 of this post, the source code in the event handlers within each controller was removed. That’s because there’s some interesting stuff going on that wouldn’t have made sense without first knowing about one last module within the application: eventBroadcast.

To communicate clicks and cats between controllers, I found a dead simple solution that cobbles together an event dispatcher-esque system. When ‘eventBroadcast’ is injected into a controller, it will have access to its member variables – in this case, an event name, and a message. The eventBroadcast object can also broadcast events from the $rootScope, which will then trickle down the scope hierarchy and can be listened for by each controllers $scope. So it goes something like this:

1. User clicks a cat thumbnail
2. $scope.getDetail is called.
3. The clicked cat object is attached to eventBroadcast.message.
4. An event is broadcast from $rootScope with the name ‘catClicked’
5. CatDetailController’s $scope responds to ‘catClicked’
6. eventBroadcast.message is checked for data.

Here is the ngClick handler in CatListController:

Here is the actual eventBroadcast module:

And the handler for ‘catClicked’ in CatDetailController:

And there you have it! A rudamentary technique for communicating between controllers. However, after reading , I learned that there are some flaws with this method. Thomas Burleson created a more robust pub/sub module that acts as a message queue, which is more scalable, flexible, and doesn’t rely so much on $rootScope. A demo of the Messaging Service module is on jsFiddle, and the code can be download from his site. I hope to try this out very soon.

Continued from: Angular Cats! Part 1
Full Source Code: GitHub: jsCats/ngCatsHOM

Gathering a pile of data from an API (or in my case, a raw json file) makes for a pretty poor web application. In order to present the data in a fun and interactive interface, I created a couple HTML templates in the /partials folder, and inserted references to those templates into the MainController section of index.html.

In order to show or hide each partial view, I created two boolean values within the MainController’s scope. The values are named ‘viewList’ and ‘viewDetail’ and setting them to true or false will show or hide each one (respectively). The HTML templates themselves are inserted with the ngInclude directive. Using ngInclude probably isn’t the best option as it can lead to spaghetti code, have adverse affects on page performance, and probably some other stuff I can’t think of. Creating custom AngularJS directives are the best option for reusable components and/or widgets. I’ll eventually get to that, but to keep things simple for now, using ngInclude will work.

The MainController has a simple function called switchView that flips the boolean values of viewList and viewDetail. I don’t have a situation where both should be true or false, but I could if I wanted. If you look at the MainController function, there are two event handlers that do nothing but call switchView().

Upon loading the app, the user is greeted with a nice big grid full of lovely little cat pictures. This grid is actually an unordered list of thumbnails from the cat data. All of the viewable elements on the page are contained within the CatListController section – denoted by the ngController directive. There are a number of directives doing different things here: The ngClick directive handles mouseclicks and calls a click-handler function; The ngMouseover directive works similarly; ngRepeat will iterate through the contents of the ‘cats’ array and create a list-item for each cat; and ngSrc will display the thumbnail in conjunction with the img tag.

That’s all fine and dandy, but it’s not going to do anything unless we actually have a CatListController. The CatListController will need to define the properties and methods within its $scope, and handle any setup or logic for the listView page. $scope methods will define the behaviors, such as responding to clicks, and will store data used by directives (e.g. catName). Also within CatListController is the call to CatService.getCats(). This retrieves all the translated cat data and stores it on the $rootScope. Storing data on the $rootScope is sort of like creating a global variable – not the best practice, but useful in a pinch. And it’s only ‘global’ within the scope of the AngularJS application, not the global Javascript namespace.

The code below is truncated. For the full source (with comments), take a look on GitHub.

The catDetail template is pretty much the same story. There are a bunch of $scope variables to store data to display within the template, and some click handler functions for buttons. A unique element that appears on this page is ng-carousel, which is a directive that activates Twitter Bootstrap’s carousel gallery component for a series of pictures. Normally, the Bootstrap carousel is activated by the ‘carousel slide’ class. However, after building the view, I noticed that sometimes the slider buttons would just stop working. It was very intermittent, and I think Angular refreshing the DOM on $scope changes would somehow break the carousel. To fix this, I created a directive that would refresh the carousel component every time the $scope.cat variable changed.

Oh yeah, did you see that ng-bind-html-unsafe directive? That’s because the description text has a bunch of craptacular MS Word-to-HTML junk sprinkled throughout, and that particular directive handles it quite nicely.

The controller here is pretty straightforward – handle clicks, show a cat.

And here’s the directive to fix the Bootstrap carousel problem:

Last but not least is a technique to give the controllers the ability to communicate with each other. But that will be a separate post, because this one is too long already.

View the App | Get the Code

In order to broaden my horizons as a developer of web applications, I’ve been taking a good hard look at some of the popular Javascript MVC frameworks of the modern era.  I started by looking at backbone.js and was horribly confused, and was subsequently delighted when I investigated AngularJS.  The ‘two-way declarative bindings’ remind me a lot of Flex, and it felt very natural jumping into development with Angular.  In order to stretch my brain a bit, and really dig into the framework, I decided to start simple and convert an existing Flex project into an Angular app.  A perfect candidate for this is the House of Mews cat browser.  It’s a simple little widget that pulls pet data from the Petfinder.com API, displays a grid of thumbnails, and allows a user to browse details of adoptable pets.

Try it out!

To get started, I grabbed the angular-seed project from GitHub.  This project includes the latest version of Angular (1.0.2 as of this writing), as well as some tools to run a stand-alone server using node.js, and a unit-test runner.  All I really paid attention to was the contents of the ‘app’ folder. It has a nice directory structure, some starter files, and the library itself.

After clearing out all the cruft, I started with the app.js file in /app/js/. Using a single statement, I defined the main module for my app.

Then it’s a simple as adding the ngApp directive to the root of the index.html document. Oh yeah, I also added Twitter Bootstrap to the project as well. The grid system is just super, and I wanted to use the carousel they provide.

Before going any further with HTML and partial templates and such, I like to make sure I can grab the data first. I created a service module to gather all the cat data. Because the cat data is only updated once per week, I simply download a data file using the Petfinder API, and load the data directly from my site. This prevents hundereds (thousands?) of unnecessary calls to the Petfinder API, since the data rarely changes. I actually have a PHP script that runs every week to update the local data file.

The angular service module is really a factory that does two things: Uses Angular’s $resource object to load data from cats.json, and create a CatService object to be used throughout the application. For now, this object only has one method: getCats(). Rather than just pass raw data from cats.json around the application, getCats() will first transform all the raw data into a nice collection of sensible Cat objects. To see what I mean, observe the raw data for a single cat below:

Now look at this:

Much better, no? It’s a lot easier to work with these tidier objects in the controllers and templates, plus, some validation and manipulation makes it easier to handle cases where data is missing.

Here’s the barebones service module. Too see the full source code (including the ServiceHelper module which does all the data translation), take a look at the project on GitHub.

So that’s a good start. The application won’t really do anything, but it’s primed and ready to fetch lots of cat data!