[[TOC]]
= Locations Hierarchy =

Provide a flexible Locations Hierarchy.

These are the 'Admin Boundaries': L0 - L4

Adding of locations within the L0-L4 range should normally be done by the Administrator prior to going live with the deployment so that these can then be locked-down to the !MapAdmin role to prevent duplicate name entries.

Default names (customisable in {{{models/000_config.py}}}):
{{{
deployment_settings.gis.locations_hierarchy = {
    "L0":T("Country"),
    "L1":T("Province"),
    "L2":T("District"),
    "L3":T("Town"),
    "L4":T("Village")
}
}}}

Since most deployments are restricted to just 1 or few countries, it is possible to hard-code which ones are used (in {{{models/000_config.py}}}):
{{{
deployment_settings.L10n.countries = ["PK"]
}}}



== Location Selector ==
There are 6 ways of adding a location, listed in ideal order:
 1. '''Bulk import''' has either Location Names or Lat/Lons
 * This could optionally use Image EXIF headers or a timesynced GPX file
  * NB: This refinement can be added later
 2. '''HTML5 !GeoLocation''': If the resource is one where the user is likely to be physically at the relevant location
 * e.g. pr/person/presence can be recorded automatically upon login
 * We should use a 'nearby' algorithm (like {{{gis.get_features_in_radius()}}}) to re-use existing locations rather than adding a new one each time.
 * NB: This refinement can be added later
 3. '''Map''': User clicks on a location on the map
 * If we have admin boundaries available then:
  * We can zoom to the correct area if a level of hierarchy has been selected
  * The correct hierarchy can be filled-in automatically
 * If not then the user can be prompted to provide these (as per 6)
 4. '''Manual Entry of Lat/Lon''': (either from a GPS or looked up in an online resource like Wikipedia)
 * A Conversion tool is available to convert from Deg/Min/Sec to Decimal Degrees
 * If we have admin boundaries available then the correct hierarchy can be filled-in automatically
 * If not then the user can be prompted to provide these (as per 6)
 5. '''Geocoder''': Street Address is entered & this is matched to a location via a Geocoding service
 * We already have functionality ready for Google & Yahoo in {{{modules/s3gis.py}}}.
 * We need to add at least [http://geonames.org Geonames].
 6. '''Hierarchical Selector''':
 * We have dropdowns for each of the different levels.
 * The country selector should remain hidden if there is only 1 country being used.
 * Initially just a single dropdown should be displayed.
 * When this dropdown is selected then the next dropdown is displayed, along with appropriate values
  * We download the values via AJAX in order to not have to download all Locations, however we could download the next set in the background whilst the user is thinking: means a bigger download to filter client-side, but maybe less time overall. Can be experimented with.
 * When the final dropdown is selected then the user has the option of adding a more specific Name & a Street Address
  * This should not be mandatory as some records need to link directly to the L0-L4 levels.

If adding a new Location, then the name of the location should *not* be the general name, but rather a specific one
 * Where possible, we automate this by using the name of the Shelter or Hospital
  * Should we prevent 'Add Location' from working until that field is filled-in?
 * We need to make this clear in the online help.

We want to be able to optionally specify which levels of hierarchy we are interested in for this resource.

== Agasti ==

Sahana Phase2 has a nice hierarchical Locations system:
 * http://wiki.sahanafoundation.org/doku.php?id=dev:location_handler
This is useful for categorising data for Reporting purposes.

It doesn't have any link to GIS though....we need to be able to link the Locations to GIS polygons.
 * [http://thematicmapping.org/downloads/TM_WORLD_BORDERS-0.3.zip Sample Polygons for Country-level boundaries]

The definition of Locations can be different in different sectors (not just the names of the locations, but also their actual boundaries)[[BR]]
e.g.:
 * category = "Health" would have types = National, Regional, Provincial, District, MOH Divisions, PHI areas, etc
 * category = "Governance" would have types = National, Provincial (or state), District, Division, Tribunal (or Gramasevaka area)

----
[wiki:BluePrintGeographicInformationSystems GIS BluePrints]