Overview

If you are developing a web application or website that requires user to provide a location (address of their house, business, establishment etc) for visitors in Philippines, It might be useful for them to select from a list of Cities or Barangay instead of typing everything in a text field.

The Problem

There is around approximately 42,000 plus barangays in the Philippines. Let alone the list of cities. Storing this amount of data just to display this kind of dropdown is too much of hassle and load for most applications. Not to mention, that you need to have the copy of this data in every database that needs this, there should be a better way of doing it...

The Solution

I've developed a jQuery Plugin that allows you to turn any <select></select> element into a dynamic one, so that its list of <options></options> is automatically populated by data via AJAX request.
The AJAX request is being initiated into a FREE REST API (that I've also developed) which is pretty much responsible for returning the list of items depending on the filter and option you specified when invoking the plugin.

Quick Demo

Here is a very simple demo of what the plugin can do. Below, you could see we have 4 dropdowns. Each is being populated dynamically by the plugin, depending on the value of the dropdown above it
demo cascading dropdown See LIVE DEMO

  • Region is populated upon page load
  • Province is populated depending on what is selected in Region
  • City is populated depending on what is selected in Province
  • Barangay is populated depending on what is selected in City

// attach handlers when user had selected an item in the dropdown   
    $('#region').on('change', function(){ // fill province dropdown });
    $('#province').on('change', function(){ // fill cities dropdown });
    $('#city').on('change', function(){ // fill barangay dropdown });
    
    // call the plugin to those dropdowns with the proper location_type
    $('#region').ph_locations({'location_type': 'regions'});
    $('#province').ph_locations({'location_type': 'provinces'});
    $('#city').ph_locations({'location_type': 'cities'});
    $('#barangay').ph_locations({'location_type': 'barangays'});
    
    // fill up the regions dropdown, so user can start "drilling down"
    $('#region').ph_locations('fetch_list');

Note that this plugin doesn't requires you to install any backend script in your app. You can use it in any static website that have jQuery. Interested? head over to the Installation to start using it!

Installation

install it by putting this in your HTML code (head or right before footer) 
<script src="https://f001.backblazeb2.com/file/buonzz-assets/jquery.ph-locations-v1.0.2.js"></script>
or save the copy of the file above and upload the jquery.ph-locations-v1.0.2.js somewhere in your server and reference it.

Usage

create the markup

<select name="city" id="my-city-dropdown"></select>
initialize the control 
$('#my-city-dropdown').ph_locations({'location_type': 'cities'});
populate the dropdown with items (and optionally pass any filter) 
$('#my-city-dropdown').ph_locations( 'fetch_list', [{"province_code": "1339"}]);
see more below about the codes assigned for each location.

Configuration
When initializing the plugin, you need to pass the location_type setting so that it knows what kind of data you are trying to display (region, province, city, barangay). The possible values are:
  • regions - this dropdown will gonna be filled with list of region
  • provinces - this dropdown will gonna be filled with list of province
  • cities - this dropdown will gonna be filled with list of cities
  • barangays - this dropdown will gonna be filled with list of barangay
in order to populate the dropdown with items, you need to call the fetch_list function by the plugin. The fetch_list function can accept filters that allows you to limit the number of items to show. For example, the dropdown above will list only show cities that is under Manila City, represented by province_code 1339. The 1339 value is the assigned code by Philippine Standard Geographic Codes (PSGC)

You can also check the source code of the demo to see how it is used.

About

Why Philippines only? why not a plugin that can list every possible location on earth?
That would be a very generic project that its usefulness is very minimal, as each country might have their own way of classifying smaller towns and cities. For example, "barangay" is something very specific to Philippines only. We also have our own way of classifying geographical locations as defined by Philippine Standard Geographic Codes (PSGC) which only makes sense in Philippines usage but not outside the country.

Credits