[[TOC]]
= Location Selector =
We want a widget which can be embedded within a form to be able to select the appropriate location to associate with a record using either hierarchical dropdowns or a precise location.

== Status ==
We have a widget in {{{views/gis/location_autocomplete.js}}}
 * this is added manually to many view templates (often this is the only customisation for that view)

This supports:
 * [wiki:BluePrintGISLocationsHierarchy Hierarchical Level] selector to choose the correct level or select the correct Parent
  * The country selector remains hidden if there is only 1 country being used (as per deployment_settings).
  * The number of levels available depends on the deployment_settings.
  * Initially just a single dropdown is 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
 * The user has the option of adding a more specific Name & a Street Address
  * This is not mandatory as some records need to link directly to the L0-L4 levels.
  * New locations have their name automatically set from that of the Record, if no other name is provided
 * Map-based lookup of !Lat/Lon
 * Manual entry of 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

== !ToDo ==
 * Redesign the !Look/Feel to make it more usable
  * Ensure that Sites *always* have a specific location
   * This location should be the Building (which can be shared by multiple sites) or a Location Group (Site spread over several Buildings)
    * Ensure that Name field is labelled as Building Name unless a Group is being used
  * Presence records or misc locations don't need a Name at all (optional)
  * Display all the Lx layer dropdowns from the start?
  * Q: Should we save a new location automatically upon submission of main form (as now) or else have a manual Save button?
  * Q: Is 'Specific Location' == L5?
 * Add an HTML5 !GeoLocation option ('Current Location')
  * 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.
  * e.g. pr/person/presence could be recorded automatically upon login 
  * display the results on a map for visual confirmation that the correct result has been returned
 * Set the map entry default !lat/lon/zoom based on the selected Level in the Hierarchy (assumes we have at least Centroid information available, ideally use Polygons where we have them)
 * Display the geocoder results on a map for visual confirmation that the correct result has been returned
 * [wiki:BluePrintGISGeolocator Geocoder] lookup of a Street Address (port from old Selector)
  * Use more Geocoders than just Google
 * If we have admin boundaries available then the !Lat/Lon provided can be validated against the selected !Lat/Lon
 * If we have admin boundaries available then the correct hierarchy can be filled-in automatically if just the !Lat/Lon are provided
 * Experiment with downloading all Locations at startup (into a [http://api.jquery.com/data/ jQuery Data store]) & filtering client-side, or maybe downloading just the full next level of hierarchy proactively (e.g. we've got the L0 selected, we have the L1 dropdown populated accordingly...we could download *all* L2s within the L0 ready for when the L1 is selected & then filter the downloaded L2 data to those within the relevant L1 to populate the L2 dropdown with). This would also provide an automatic cache (within the page only).
 * Extend the location_id() API to support controlling which levels of hierarchy we're interested in for a resource (some may be only interested in the province, whereas others may need a precise location)
 * Make the gis/location/create form reuse as much of this UI paradigm as possible (although the focus for that screen will be adding the Admin Hierarchy)
 * Implement ideas from BluePrintResourceSelectAdd
=== Known Issues ===
There are various bugs in the current implementation, some of which are listed below.

==== Duplication of location records ====
This happens when you for example create a new hospital record without creating a new location, but just selecting one (just select a country, for example). When you submit, then a new location record is created with the same name as the selected one - this seems wrong. You can make it visible by uncommenting the show_status line. The reason for this behaviour is that S3.gis.uuid is empty in case there is no old_location, which triggers the creation of a new record. Thus, this does not happen in update, and not either when you create a new location (which creates a new location anyway :D).

----
PakistanDevelopers#LocationsSelector

[wiki:BluePrintGISLocationsHierarchy]

[wiki:BluePrintGeographicInformationSystems GIS BluePrints]