Railsmagazine60x60 geography_division_select tag

by Satish Kota

Issue: Winter Jam

published in December 2009

Satish Kota is the founder and chief technical architect of Heurion Consulting Pvt Ltd, www.heurionconsulting.com, a small RoR shop based in Bangalore, India. He has about 10+ years of experience in developing software for various industries and has worked on multiple technologies such as Ruby on Rails, PHP, Microsoft etc.

His interests in Ruby on Rails help him not only develop exciting applications, but also promote the technology. Satish is the Moderator of Bangalore's Ruby Users Group and also provides Corporate/Institutional Training in India. If you have any projects to be executed or training to be conducted, you can reach Satish at satishkota /at/ heurionconsulting /dot/ com.

Satish is also the promoter of www.abilitz.com (built on Ruby on Rails and promoting jobs for Freshers in India).

Introduction

There has been so many plugins in Ruby on Rails space and we have been always re-inventing the wheel and writing again and again… Why do we do that? One of the main reasons are that many plugins have been built for particular reasons but never integrated them. One of these plugins is the country_select. state_select is yet another one. The former is used to select countries and the later to select the state. What happened to the regions… should we write one more plugin to say region_select or continent_select? This motivated me to integrate all the plugins so that we have one plugin. When I started to write the geography_division_select I had in mind that I want to integrate regions, countries and states. But by the time implementation completed, I had added multiple features such as conditions, priority list and selected options.

What does Geography Division Select do?

Geography Division Select is a select tag which helps developers to display all divisions of the World. This plugin is similar to the country_select and state_select plugins and includes both mechanisms. Using Geography Division Select a user can:

  • List all the Regions (Continents) of the world (based on conditions)
  • List all the Countries of the world (based on conditions)
  • List all the States/Provinces/Districts etc, for Each (or more) Country(ies) - based on conditions
  • Provide drill downs based on :only and :exclude conditions
  • Support priority listing
  • Support preselected listing

Geography Division Select can be used by in multiple ways:

  • By using geography_division_select with object and method and option. This creates an HTML SELECT tag along with OPTION tags.
  • By using Rails select_tag and sending the options by use of geography_division_options_for_select.
  • By using HTML SELECT tag and wrapping around Option Tags by use of geography_division_options_for_select.
  • By using geography_division_select as part of Form Tag.

Where is the plugin available?

It is available on github:

git clone git://github.com/heurionconsulting/geography_division_select.git

Usage

Geography Division select can be used in two ways:

  1. Select tag which generates the HTML SELECT and OPTION tags: geography_division_select(object, method, options, html_options)

  2. Select tag which generates just OPTION TAGS which can be wrapped around a HTML SELECT TAG:

geography_division_options_for_select(options)

The main entity that controls the display of geography_division_select is the options section. The main supported elements are:

  • :drilldown - This keyword identifies the type of data to be shown as part of dropdown. Supported types of drilldown are: 

    •  :drilldown => country" - displays the countries of the world based on conditions. 

    •  :drilldown => "state" - displays the states/provinces/atolls/islands,etc., of a country based on conditions: 

    •  :drilldown => "region" - displays the regions (continents) of the world based on conditions. This is the default type of drilldown.

  • :selected - This keyword identifies which option in the dropdown has to be preselected.

  • :priority - This keyword identifies if there is any priority selection that has to be provided along with the complete list. This helps if the developer wants to ensure priority for a particular country/state/region.

  • :only - This keyword provides support to identify conditions for the drilldown to provide display of that particular or set of drilldown elements. Only Conditions has to be used in conjunction of the drilldown type to identify better selection of drilldown data.

  • :exclude - This keyword provides support to exclude a list of options while creating the dropdown options. Just like :only condition, :exclude condition can be used in conjunction of the drilldown types to allow better selection of drilldown data.

Notes

:only and :exclude conditions can have multiple drilldowns as part of the conditions. It helps in making correct query of options that are displayed:

:only => {:country=>"United States Of America", :region=>"North America"}
:exclude=>{:country=>"India", :state=>"Karnataka"}

For any select tag both :only and :exclude can be used together:

{ :only => { :region=>"Asia", :country=>"India" }, :exclude { :state=>"Karnataka" }}

Any conditions either in :only or :exclude you can use multiple elements (separated by comma)

:only=> { :country => "India, United States of America, United Kingdom, France, Spain" }

:exclude => { :region => "Africa, Asia, North America" }

:only => { :region => "Asia, Africa, North America"}, :exclude => { :country => "India, United States Of America, South Africa" }

By using :only conditions care has to be taken to ensure that the parent of the drilldown would be neglected. The various options are:

  • Has region drilldown only: both the country and the state are considered if they are part of :exclude condition.

  • Has country drilldown only: only the state is considered if it is part of :exclude condition. If the region is part of :only or :exclude condition it is not considered for calculation of states.

  • Has state drilldown only: only the state is considered. If region or country is part of :only or :exclude condition, they are ignored for calculation of list of states. Examples:

:only => { :region => "Asia" }, :exclude => { :country => "India", :state => "Karnataka" } # Valid

 

:only => { :country => "India" }, :exclude => { :region => "North America"} # the same as :only => { :country => "India" }

 

:only => { :region => "Asia", :country => "India"} # the same as :only => { :country => "India" }

 

:only => { :state => "Washington" }, :exclude => { :region => "Asia" } # the same as :only => { :state => "Washington" }

 

:only => { :state => "Washington" }, :exclude => { :region => "Asia", :country => "United States of America" } # the same as :only => { :state => "Washington" }

 

:only => { :country => "United States of America", :state => "Washington" }, :exclude => { :region => "Asia" } # the  same as :only => { :state=> "Washington" }

 

:only => { :region => "North America", :state => "New York" }, :exclude => { :country => "United States of America" } # the same as :only => { :state => "New York" }

 

:only => { :region => "North America", :country => "United States of America", :state => "New York" } # the same as :only => { :state => "New York"}

That's it! you are ready to use the plugin.

Examples

The ReadMe file has many examples, the first ones are listed below for illustration. You can just copy and paste these examples in a view to get a better understanding of the options.

Default Entity:

<%= geography_division_select("geography","geography") %>

displays all the 7 regions of the world.

Region Drilldown using Region Only Conditions:

<%= geography_division_select("geography", "geography", :drilldown => "region", :only=> { :region => "Europe, North America, South America" }) %>

    displays the 3 regions as set in the :only conditions

Region Drilldown using Region Exclude Conditions:

<%= geography_division_select("geography","geography", :drilldown => "country", :exclude => { :region => "North America, South America" }) %>

displays the all the regions of the world except regions declared in :exclude condition.

Country Drilldown:

<%= select_tag("geography", geography_division_options_for_select( :drilldown=>"country")) %> 

displays all the countries in the world.

State Drilldown using Country in Only conditions:

<select name="geography">

<%= geography_division_options_for_select( :drilldown => "state", :only => { :country => "India" }) %>

</select>

displays all the states of India.

State Drilldown using Country in Only conditions:

<select name="geography">

<%= geography_division_options_for_select( :drilldown => "state", :only => { :country => "India, United Kingdom" }) %></select>

displays all the states of India and United Kingdom.

Future work

I have tried my best to implement everything, however there are still formatting options that I need to provide. Currently when a developer selects a country, only countries will be listed and so is with regions and states. However I have plans to implement formatting options such that we display a drill down mechanism to allow users to view the dropdown in a much better fashion. So much for the next version.

Resources
Plugin page