Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A wrapper for the ActBlue.com API
Ruby
Branch: master
Pull request Compare This branch is 16 commits ahead of netroots:master.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
spec
.gitignore
.rvmrc
Gemfile
README.textile
Rakefile
ruby-actblue.gemspec

README.textile

The ruby-actblue gem is an object mapping for the ActBlue API.

Two environment variables need to be set before use: ACTBLUE_USER and ACTBLUE_PASS. This username password combo are the same email/password credentials you would use to log into secure.actblue.com.

ENV['ACTBLUE_USER'] = <EMAIL>
ENV['ACTBLUE_PASS'] = <PASSWORD>

If you are using Bundler, add something like this to your gemfile:

gem 'ruby-actblue', :git => 'git://github.com/woodhull/ruby-actblue.git', :require => "actblue"

Terms

A Contribution represents a donation from a given source to a given destination.

A Page represents a fundraising campaign. A Page also literally translates to an explicit url on actblue.com. Pages can have one or many candidates or entities associated with them.

Capabilities

The ActBlue API is somewhat restricted compared to its base Indigo documentation. The Ruby wrapper acknowledges this reality and only exposes what you can do.

You can:

  • Get Contributions for a given entity (candidate)
  • View Pages
  • Create new Pages
  • Update Pages
  • Delete Pages
  • View Entities

Note that you cannot post Contributions through the ActBlue API. We will be sending people directly to actblue.com to make contributions.

Library

Creating Objects

This library has a specific way to build and read API objects. Each class can take parameters for API variables in the constructor. All variables for an API object can be later read/written to by using the [] operator. For example:

# Create a new Page object
@p = Page.new("title" => "My New Campaign")

...

# Modify the title later
@p["title"] => "My Awesome Campaign"

# or use the ruby style accessor

@p.title = 'My Awesome Campaign'

# Look at all the variables
@p.variables.inspect
=> {"title" => "My Awesome Campaign"}

# or a specific one.

@p.title.inspect
=> "My Awesome Campaign"

Original ActBlue field names are available with the [] operator – this allows access to attributes and elements that have a ‘-’ dash in their name. Ruby equivalents to these names are available as accessor methods with the dashes replaced with underscores.

When creating objects with nested elements you should use the corresponding API objects. For example if I wanted to add some Listentries to the Page object we were working with above:

@p["listentries"] = [ListEntry.new(:blurb => "kyle"), ListEntry.new(:blurb => "another")]

Calling ActBlue

We mentioned above that the API can only really do 4 things at a high level. As a result you will only be calling ActBlue via the two main API objects: Contribution and Page.

The goal of the library was to have a complete object mapping both when building and receiving API objects. The result of every call you make to the ActBlue API will be exactly like the objects you built.

All of the methods on the Page class (post, put, delete) return the actual response from ActBlue which you will have to interpret. Call .code on the response object to get the HTTP code returned with the call. You will have to deal with errors and problems within your application.

Contribution.get

Contribution.get queries ActBlue for Contributions that match your parameters. The parameters hash can contain any of the variables specified within the Indigo API. For the most part we’ll only need to do a few different kinds of queries.

# Don't do this.  This is actually asking ActBlue for all the contributions ever and it won't work.
Contribution.get()

# Get all Contributions for Brian Moran.  Notice the destination parameter.  It corresponds to Brian Moran's entity id within the ActBlue system which is 20930.
@contributions = Contribution.get(:destination=> "20930")
=> [contribution1, contribution2, ... ]

# Get all Contributions for a given Page.  This wasn't documented in their API docs but it works.  Pass in the page parameter with the page name attribute.
@page_contributions = Contribution.get(:page => "bmoran")
=> [contribution1, contribution2, ... ]

# Get a summary of all the Contributions for Brian Moran.  This will just return some stats on all the contributions that match the query.  The count, sum and average are supposed to be part of this summary return.  In practice though I have only seen the count returned.
@contributions_summary = Contribution.get(:destination => "20930", :view => "summary")
=> {"count" => "2", "sum" => "100.00"}

Page.post

Create an instance of a Page with all the variables you want. title, name and author must be set in order to create the page.

@p = Page.new(:title => "my page", :name => "mypage", :author => "Kyle")
@p.post

Page.put

Using the @p Page instance from above…

@p['title'] = "My Newer Page"
@p.put

Page.delete

Using the @p Page instance from above. This simply sets the “visibility” Page variable to “archived” which on ActBlue means deleted.

@p.delete

Page.get

Retrieves page metadata for an existing fundraising page.

@p = Page.get 'reidstandingstrong'

Entity.get

Retrieves entity metadata for an existing fundraising recipient.

@e = Entity.get 1234
Something went wrong with that request. Please try again.