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}[http://www.rubydoc.info/github/jim/carmen/master/frames] 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
See CHANGELOG.md
== Credits
This project is only possible because of the work of {many fine developers from around the world}[https://github.com/jim/carmen/contributors].