An Intro to NationBuilder App Development with Ruby on Rails

NationBuilder is a powerful CRM and website builder with services for sending bulk emails,  collecting donations, hosting events, and more. However, it doesn’t do everything, and that’s where a custom application and NationBuilder’s API can fill the gap.

This guide will walk you through setting up a brand new Ruby on Rails application with all the basics you need to start interacting with NationBuilder’s API. At the end we’ll be able to create and update people in NationBuilder from our application.

This guide was inspired by Up At Five’s Shopify app tutorial, which you can find here.

You should have some familiarity with programming, using your computer’s terminal, and NationBuilder. If you don’t yet, there are hundreds of guides online to get you started. It’s really not hard, and anyone can do it! Let get started.

Installing Ruby and Ruby on Rails

To get started you’ll need to have Ruby and Ruby on Rails installed. There are many guides about this already, so here are some links. Ruby comes preinstalled on Macs, so you can skip to Installing Rails in that case.

If you’re using Windows, try this guide: Installing Ruby on Windows
For the few remaining Linux users, try this guide: Installing Ruby

To install Ruby on Rails on any system, follow this guide: Installing Rails

I’d also recommend installing a coding text editor, if you don’t have one already. I recommend Atom, but Sublime and Visual Studio are popular choices too.

Setup NationBuilder

I’m guessing if you’re reading this, you already have a NationBuilder account. But if you don’t, just head to https://nationbuilder.com/ and sign up. They offer a free trial, and plans starting at $29/month.

You’ll also need the Developer settings enabled on your account, so if you don’t see the Developer tab in your nation’s Settings, contact [email protected] to request access.

Once you have the Developer tab in your Settings, select it and then select “API token” and create a one. You’ll see your tokens listed there, and we'll come back to this soon. These tokens are for testing and development only, and production applications should use OAuth to authenticate users, but we’ll keep it simple today.

Creating a Ruby on Rails App

It’s time for the fun stuff! We’re going to create a new Rails application, so we can start coding.

In your terminal\command prompt enter this command, replacing <app name> with whatever you’d like to call your new app:

rails new <app name>

This might take a little while to run, as it’s creating all the files needed for our shiny new application. Once it’s done, you can navigate into the app’s folder:

cd <app name>

Next up, we’ll be using NationBuilder’s Ruby gem to simplify making calls to their API. Let’s add it to our app’s Gemfile:

echo "gem 'nationbuilder-rb', require: 'nationbuilder'" >> Gemfile

We’ll also install a gem called dotenv, so we can keep our API token safe:

echo "gem 'dotenv-rails', groups: [:development, :test]" >> Gemfile

Now we can install all the gems:

bundle install

And run our app:

rails s

Congratulations! You’ve successfully started your Ruby on Rails application. Try visiting localhost:3000 in your web browser, and you should see this:

Setting up Your Application

Now we’re going to setup your app. Start by opening your app’s project folder in your preferred text editor. You should see something like this (this is in Atom):

We’ll need to create a table, model, controller and views for our app to work with people records. In your terminal, type the following:

rails g scaffold Person first_name:string last_name:string email:string

That’ll create everything we need to manage people with first and last names, and an email. Now to create the table, run:

rake db:migrate

Try running your rails server again ("rails s" in your terminal), to make sure everything starts up okay, then go to http://localhost:3000/people to see one of the pages Rails just created for us.

Let’s put our API token in the app now. In the root folder of your application, create a file called .env (that’s right, just .env). Open the file and enter this in it, replacing the <placeholders> with your real info from earlier:

API_TOKEN=<your NationBuilder API token>
NATION_NAME=<your nation’s name>

To keep this data safe, we’ll want git to ignore the .env file, so you don’t accidentally publish your API token on GitHub or anything. So open the file in your application called .gitignore and add .env to the list.

Next we need to setup the NationBuilder gem we installed earlier, so it can communicate with your nation. In your text editor, navigate to the initializers folder, found inside the config folder.

Create a new file in this folder, and call it nationbuilder.rb. In that file, we’ll enter this:

NB_CLIENT = NationBuilder::Client.new(ENV['NATION_NAME'], ENV['API_TOKEN'], retries: 8)

The “ENV” stuff is referring to the variables we setup in the previous step, so it will fill in your nation’s name and API token for you. Every time your app starts up, it’ll create a NationBuilder API client for us. Now we can working with NationBuilder data from within our app. Let’s do it!

Saving People in NationBuilder

When you create or update a person in your app, let’s send their details to your nation too. In your text editor, open the people_controller.rb file. On the third line of the file, just under before_action :set_person, only: [:show, :edit, :update, :destroy add this:

after_action :send_to_nationbuilder, only: [:create, :update]

And then near the bottom, you’ll see a line that just says “private”. Just below that line, add this:

# Send a person to NationBuilder
def send_to_nationbuilder
  NB_CLIENT.call(:people, :push, person: person_params.to_h)
end

Let’s test it! Start your server again (remember, “rails s” in your terminal), and go to http://localhost:3000/people/new in your browser. Enter a name and email, and click Create Person. You should see something like this in your browser:

Now in another tab, go to the People view in your nation’s Control Panel, and you should see the person in your list of people:

Amazing! We’re working with NationBuilder’s API. Easy, right? Try making a few more people in your app, and see what happens.

Let’s also try updating someone’s information, to see if it updates in NationBuilder too. Go to http://localhost:3000/people to see a list of all the people you’ve created in your app. Click Edit next to one of them, and try changing their name, then click Update Person. Go back to your nation’s Control Panel, and you’ll see their name has been updated there too!

Wrap It Up

That’s an excellent start to building a NationBuilder application with Rails. NationBuilder has dozens of API endpoints, where you can create, read, update and destroy all kinds of data, including people, events, tags, RSVPs, pages and more.

Some further reading, to continue your Rails + NationBuilder love affair:

• NationBuilder API Documentation
• NationBuilder Ruby Gem
• cStreet Campaign’s Blog, with lots of great stuff about NationBuilder

I’ve uploaded this app to GitHub, so feel free to check it out and clone it here. Please reach out if you have any questions or feedback to [email protected].