Version 54 (modified by Fran Boon, 13 years ago) ( diff )


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.


We have a widget in modules/s3/ and static/scripts/S3/s3.locationselector.widget.js

This supports:

  • 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.
      • Assessments
      • Projects (even some Activities)
    • New locations have their name automatically set from that of the Record, if no other name is provided (still?)
  • 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

Use Cases

Locate a Site/Address

Addresses are like Sites (although less likely to need a Location Group)

Q: Should we make Addresses Sites?

  • Advantage: they have much in common from the PoV of the Location Selector
  • Disadvantage: harder to filter out Addresses (need to add UI for optional filtering support on Autocompletes)


  • Select an Existing Building
  • Create a New Building
    • Enter the Address & use a Geocoder to open a focussed map view to allow precise selection of Lat/Lon
      • e.g.
      • deployment setting to say whether this is the preferred option? (I'm not sure how useful it is in some countries)
    • Enter the Address & open a map view to allow precise selection of Lat/Lon
    • Enter the Address & Lat/Lon manually
  • Select an Existing Location Group
  • Create a New Location Group
    • Workflow should do this as easily as possible rather than having to manually create the Group & then Create New Building(s) within Group
    • Have a checkbox within form 'Multiple Locations' which creates the Location Group (with the same Name as the Site + 'Group')
    • The 1st Building is created in the normal way & added to this group
    • Q: How do we add subsequent buildings? (Lower priority for now)

Locate a Person

Link them to a Site/Address

  • Set a Staff member's Base Location to their Office Address
  • Set a Volunteer's Base Location to their Home Address
  • Check-in to a site

Both would want to select Site from a Dropdown (ideally Combobox)

Can tick 'Base Location' when adding/updating an address

Provide a WayPoint

i.e. Presence outside a Site


  • Open a map view to allow precise selection of Lat/Lon
  • Enter the Lat/Lon manually
  • HTML5 GeoLocation

Name shouldn't be required.

Locate an Incident or Activity


  • Select a Site/Address
  • Provide a WayPoint (as for Persons)

Locate a Project or Document


  • Assessment (RAT or Flexible Impact)
  • Plan (DRR, Evacuation, etc)
  • Policy

Select Lx Hierarchy or Location Group to which this is relevant.

  • ideally provide an option to be able to restrict which Lx level(s) can be selected
  • no need for a specific location


When instantiating the Selector server-side we can differentiate between the following Modes.

Q: When a single Mode has several different workflows, should we provide a wizard-style approach to selecting between the options?

Building (Site, Address)

Client side options:

  • New Building
  • New Location Group
  • Select existing Building
  • Select existing Location Group

WayPoint (Presence, Incident)

Client side options:

  • Select existing Site/Address (make addresses sites?)
  • Create new WayPoint

Project or Document (Assessment, Plan, Policy)

Client side options:

  • Select existing Lx
  • Select existing Location Group
  • Add new Lx (optional: often hidden, especially for higher levels)
  • Add new Location Group


The options that need to be set by the modes (or within a mode) to control aspects of the Location Selector:

  • Are we requiring a Specific Location?
    • If we don't require a specific Location, then which Lx levels are acceptable?
    • Dow e ever need to provide for cases where we can select either a specific location or an Lx?
  • Does the Specific Location have a Name field?
    • What is it's Label? (e.g. 'Building Name')
    • Is the field mandatory? (Never?)
  • Should the Detailed Location fields be open by default?
    • For a Create resource which needs a specific location
    • For an Update resource which needs a specific location


  • 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)
  • Geocoder lookup of a Street Address
    • port some code from old Selector
    • Display the geocoder results on a map for visual confirmation that the correct result has been returned
      • Use this for UI example:
    • Use more back-end 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 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).



GIS BluePrints

Attachments (2)

Download all attachments as: .zip

Note: See TracWiki for help on using the wiki.