Pilgrim

---

Choose countries, states and cities via Ajax

Installation

1. Add to your gemfile: gem 'pilgrim'

2. Run bundle

3. Execute: rails generate pilgrim:install

4. Run migrations: rake db:migrate

5. Run: rake db:seed

6. Add to your routes.rb: mount Pilgrim::Engine => "/pilgrim", :as => "pilgrim"

7. Add to your application.js: //= require pilgrim/application

8. (Optional) Generate the views so you can configure them executing: rails generate pilgrim:generate_views (this will save the views in your_project/app/views/pilgrim)

9. Watch the test/dummy for an example (watch the welcome controller and its views)

---

Use

1. Add in the action where you will need to load the countries for the view: get_locations

2. Add in your view inside of a form: <%= select_location_tag :data %> where “data” is the name of the form

---

Controller Methods

get_locations(country_id = 0, state_id = 0, city_id = 0) gets the countries, the states of the first selected country, and the cities of the first state inside of 3 collections: @countries, @states, @cities. The parameters are for pre-select the options in the dropdowns.

---

Helper Methods

select_location_tag(form_name, params = {}) display the dropdowns for the locations. This is an example of a hash for params:

...
params = {
  block:  "main",
  country:  {
    name:  "country_field_name",
    html_class:  "some_class"
  },
  state:  {
    name:  "state_field_name",
    html_class:  "some_class"
  },
  city:  {
    name:  "city_field_name",
    html_class:  "some_class"
  }
}
...

Where block defines an id, so you can use the helper as many times you want changing the value in this key; the configurations for country, state and city are separated and in each one you can define the field name and the class you want to use for each element.