Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Sweetest rails address implementation ever (maybe).
Ruby JavaScript
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.



Direct Address provides a rails app with simple address features. This is a streamlined implementation of address functionality. Direct Address provides you with address, country, and region classes. It also provides a generator which generates the necessary javascript and rake tasks to implement properly. You'll also get form helpers to easily implement Direct Address in your views. A rake task is provided that allows up to date country and region information to be downloaded from


Your database must be utf-8 encoded. Country / region names will break if not.

Add direct_address to your environment.rb

config.gem 'direct_address'

Then install the gem:

rake gems:install

After you've installed the gem, you'll need to generate your classes, javascript, and rake task.

script/generate direct_address

Once that's complete, migrate your database

rake db:migrate

Now you're ready to download up-to-date country and region information from

rake direct_address:seed

This will take a few minutes and should be done on a decent connection.


Once you've run the generators there's not much you need to do. You can utilize the classes as they are or you can use the acts_as_addressable option. To use acts_as_addressable, include it in your class like this:

class User < ActiveRecord::Base

By doing this you are giving the user a single address. One thing to note is that the generator didn't create an addresses_controller or add any routes regarding addresses. By default, it is expected that the address form will be nested in the parent form. For this reason, the accepts_nested_attributes_for and attr_accessors are included in acts_as_addressable. If you'd like to implement things differently, create a controller and implement your models to your liking.

Form Helpers

By including Direct Address in your project you've added a few form helpers. Their implementation is very easy. You can either use it within a form_for like this:

<% form_for @user do |user_form| %>
 <% user_form.fields_for :address do |address_form| %>
  <%= address_form.country_select %>
 <% end %>
<% end %>

Or you can use it via a tag helper like this:

<%= country_select_tag 'user[account]' %>

Either way produces the same exact thing. Take note that this does require loading at least prototype beforehand and the country_select file before the page load is complete. If you do like to defer the loading of extra scripts, feel free to do so with country_select. The setup doesn't occur until the window.onload event is fired. An example load order would be:

<script type="text/javascript" src="javascripts/prototype.js"></script>


<% form... %>
 <%= f.country_select(:include_labels => true) %> // include_labels adds a country and region label before each selector respectively
<% end %>


Where the following call could be at either POINT A or POINT B:

<script type="text/javascript" src="javascripts/country_select.js"></script>

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2010 Mike Nelson. See LICENSE for details.

Something went wrong with that request. Please try again.