Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

file 106 lines (58 sloc) 3.855 kb

This library will work as a drop in replacement for the official Rails country_select and its various forks. The idea is to provide a single library for all geographic naming concerns, and unify them under a consistent API.

States are supported for the following countries: Australia, Brazil, Canada, China, Cuba, Denmark, Germany, India, Italy, Mexico, the Netherlands, New Zealand, Norway, Spain, Ukraine, and United States.

{API documentation}[] is available.

== Installation

gem install carmen

If you're in Rails 2.3 or earlier, place this in your environment.rb:

config.gem 'carmen'

If you're in Rails 3, put this in your Gemfile:

gem "carmen"

== Get a list of all countries

Carmen.countries => […, ['Germany', 'DE'], …, ['United States', 'US'], …] Carmen.countries(:locale => 'de') => […, ['Deutschland', 'DE'], …, ['Vereinigte Staaten von Amerika', 'US'], …]

== State list retrieval

Carmen::states('US') => [['Alabama', 'AL'], ['Arkansas', 'AR'], ... ] Carmen::states => [['Alabama', 'AL'], ['Arkansas', 'AR'], ... ] # uses default country Carmen::state_names('US') => ['Alabama', 'Arkansas', ... ] Carmen::state_codes('US') => ['AL', 'AR', ... ]

== Abbreviation handling

Carmen::country_name('US') => 'United States' Carmen::country_code('Canada') => 'CA' Carmen::state_code('Illinois') => 'IL' Carmen::state_code('Manitoba', 'CA') => 'MB' Carmen::state_name('AZ') => 'Arizona'

== Default Country

Methods that take a country code argument will use the default country if none is provided. The default default country is 'US'. You can change it to any country code:

Carmen.default_country = 'CA'

= Adding country and state exclusion to Carmen

This fork lets you exclude specific countries and/or states from Carmen. Simply set the appropriate class variables and the exclusion will take effect.

== Excluding Countries

Countries to exclude are specified as an array of country codes:

Carmen.excluded_countries = [ 'AF', 'ST', 'ZW', ... ]

== Excluding States

States to exclude are specified via a hash, with keys being the country's code, and values being the states to exclude from that country:

Carmen.excluded_states = { 'US' => [ 'AA', 'AP', 'PW', ... ], 'DE' => [ 'BW', 'TH' ], ... }

= Adding Priority Countries

It can be useful to show a few countries first in the list, before any others. This can be done like so:

Carmen.priority_countries = %w(US CA)

= Localization

You can switch between different localizations of the countries list, by setting the locale value (default is :en):

Carmen.default_locale = :de

Methods that return country names also take an optional options hash as the last argument, which can be use to override the default locale for a single call:

Carmen::country_name('US') => 'United States' Carmen::country_name('US', :locale => :de) => 'Vereinigte Staaten von Amerika'

Currently included localizations are: English (:en), Finnish(:fi), German (:de), Hindi (:hi), Netherlands (:nl) and Brazilian Portuguese (:pt)

= Rails view helpers

Carmen ships with replacements for state_select and country_select. Usage is simple:

<%= form_for @address do |f| %> <%= f.label :country, "Country" %> <%= f.country_select(:country, "US") %> <%= submit_tag "Create" %> <% end %>

== Todo

  • Many countries, such as Spain, have additional levels beneath 'state' that we would ideally support. Thanks to Alberto Molpeceres for bringing this to my attention.
  • Split the Rails-specific view helpers out into a separate gem (carmen-rails)
  • Move regex matching into an optional module.

== Changelog


== Credits

This project is only possible because of the work of {many fine developers from around the world}[].

Something went wrong with that request. Please try again.