Skip to content

Latest commit

 

History

History
136 lines (97 loc) · 3.46 KB

README.md

File metadata and controls

136 lines (97 loc) · 3.46 KB
Raw

Rails – Country Select

Build Status

Provides a simple helper to get an HTML select list of countries using the ISO 3166-1 standard.

While the ISO 3166 standard is a relatively neutral source of country names, it may still offend some users. Developers are strongly advised to evaluate the suitability of this list given their user base.

UPGRADING

An important message about upgrading from 1.x

Installation

Install as a gem using

gem install country_select

Or put the following in your Gemfile

gem 'country_select', github: 'stefanpenner/country_select'

Usage

Simple use supplying model and attribute as parameters:

country_select("user", "country")

Supplying priority countries to be placed at the top of the list:

country_select("user", "country", priority_countries: ["GB", "FR", "DE"])

Supplying only certain countries:

country_select("user", "country", only: ["GB", "FR", "DE"])

Discarding certain countries:

country_select("user", "country", except: ["GB", "FR", "DE"])

Supplying additional html options:

country_select("user", "country", { priority_countries: ["GB", "FR"] }, { selected: "GB", class: 'form-control' })

Using a custom formatter

You can define a custom formatter which will receive an ISO3166::Country

# config/initializers/country_select.rb
CountrySelect::FORMATS[:with_alpha2] = lambda do |country|
  "#{country.name} (#{country.alpha2})"
end
country_select("user", "country", format: :with_alpha2)

ISO 3166-1 alpha-2 codes

The option tags use ISO 3166-1 alpha-2 codes as values and the country names as display strings. For example, the United States would appear as <option value="US">United States of America</option>

Country names are automatically localized based on the value of I18n.locale thanks to the wonderful countries gem.

Current translations include:

  • en
  • de
  • es
  • fr
  • it
  • ja
  • nl

In the event a translation is not available, it will revert to the globally assigned locale (by default, "en").

This is the only way to use country_select as of version 2.0. It is the recommended way to store your country data since it will be resistant to country names changing.

The locale can be overridden locally:

country_select("user", "country_code", locale: 'es')

Getting the Country Name from the countries gem

class User < ActiveRecord::Base

  # Assuming country_select is used with User attribute `country_code`
  # This will attempt to translate the country name and use the default
  # (usually English) name if no translation is available
  def country_name
    country = ISO3166::Country[country_code]
    country.translations[I18n.locale.to_s] || country.name
  end

end

Example Application

An example Rails application demonstrating the different options is available at scudco/country_select_test. The relevant view files live here.

Tests

bundle
bundle exec rake

Copyright (c) 2008 Michael Koziarski, released under the MIT license