Using AngularJS with NationBuilder


AngularJS is a great framework for quickly building elegant Javascript code to enhance the user’s experience.

While with Climate for Change, I wanted to create some dynamic pages on our NationBuilder website.

While NationBuilder does allow for some server side coding through their Liquid templating, if you need the flexibility of writing fully functional code, then going client side with Javascript is the only option. AngularJS was the obvious choice as it allowed me to build functionality quickly, which meant it would fit in between my main duties.

Below are the specific changes to convention and configuration that I used to get Angular going on our site.

If you’re not familiar with AngularJS, I’d recommend the code school course and the PhoneCat tutorial to get your head around how it works. (Assuming you’re already comfortable with MVC frameworks)

In this example, I worked with Angular version 1.4.2

There were a few changes I made to the way AngularJS is usually used to get it working smoothly on NationBuilder, some obvious, some not so obvious. I’ll start with the not so obvious:

Interpolation Symbols

Angular and Liquid use the same symbols to inline variables: {{ }}

This means that any inlined variables meant for Angular will get picked up server side by Liquid and stripped out.

Abhaga on StackOverflow shows how to configure angular to use {[{ }]} instead:

Including the Javascript files

To keep things simple, I used Google’s CDN for the Angular libraries.

For our own Javascript files, NationBuilder operates on a flat directory structure, so you just place the Javascript files in the theme directory and reference them relatively (ie just the file name) and NationBuilder will take care of making sure the correct path is served up.


File Structure

Good development practice for Angular puts each component in a separate file, but this practice generally assumes that you have some kind of dependency management utility (like the asset pipeline in rails, or bower for pure javascript apps).

Such tools couldn’t easily be used with NationBuilder. If I were to follow the convention, I would have to manually add a new <script> tag to layout.html every time I created a new component. This would potentially lead to poor performance from serving up dozens of tiny javascript files, not to mention a lot of clutter in my theme because of the flat directory structure.

The compromise I found was one file per module, and broke functionality into discrete modules – one module for our actions, one for our badges, and one for the factories that served up data to both of those.

Angular Templates

NationBuilder isn’t designed to serve up snippets of code, by default pages are served wrapped in the theme. There probably is a way to do it by using different extensions or something, but that would probably mean that my Liquid variables then wouldn’t get interpreted, so rather than wrangle with NationBuilder to make that happen, I simply embedded the Angular templates within the pages that needed them.

As NationBuilder does allow for file inclusion in its templating and themes, the templates were placed at the bottom of the most specific NationBuilder template that serves the pages needed while avoiding duplication.

For example, this template that was placed at the bottom of our action.html file as it was only needed in that file.

While this snippet went into _reminder.html which was included in multiple NationBuilder templates because it was needed on multiple pages.

Development and Testing

NationBuilder website set up does not really provide for integration testing. It is possible to write some unit tests for modules and test those offline, but because server side use of Liquid can’t be easily replicated on your development machine, thorough integration testing is not easily achieved.

The most time effective solution I’ve found is to duplicate the live website on NationBuilder to create a staging environment and develop on that using the Mac Theme Sync application to allow rapid deployment of new code.

  • Nice post Chris, I always thought using Angular or React with NB was overly difficult if not impossible without an externally hosted server. I’ll have to give this a try soon and see what I come up with

    • Glad you found it useful Dev. One of the things I love about AngularJS is I find it really quick to get the framework up and running.