Location Picker & Location Active Search

[paulbalomiri]

Structure

The Location picker is an element which contains an hierarchical data set of Location bits, meaning that each bit of information refines the previous bit (Note: Bit is used in this context as in piece, not as in bits of a byte).

In the image description above a Location picker UI Widget is displayed with it's elements which shall be explained in the following List:

• Location Bit: Any Of the Elements specifying a location. Location Bits are specified by the abbrev. LB x. The following conditions hold:
  • For any two Location Bits LBx and LByfor which x<y, LBx describes a geographical area which encompasses LBy
  • Any LB must be one of be either fixed or floating
  • fixed LBs are written in bold
  • floating LBs are written in plain and accompanied by an erasure marker to the right.
  • erasing an LBx also erases all LBy for which y >= x
  • If a Location Picker is complete (Validator is set to true) no further LBs can be added to this Location Picker.
  • A LB is the first if it is LB0 and the Location Picker has no data_parent
  • the first LB must be displayed differently ( Left side is rendered without an incoming arrowhead).
  • A LB is the last if no data_child exists and it is the last LBx, that is: for all LBy in the Location Picker x >=y. Additionally the last LB is only defined if the dataset of the Location picker it belongs to is complete
  • The last LB must be displayed differently, without the trailing, outgoing arrowhead.
• Validator: A Graphical element which specifies whether the Location Picker's dataset is complete. Whenever the Location picker dataset is complete no further LB can be added to this Location Picker.
• Location Active Search:
  • The dataset is modified in the Location active search. The Location active search sets the dataset containing LBs of Location Pickers
  • When the Location Active Search receives input from the keyboard:
  • it sends this User input, together with the current dataset of the location pickers to the server
  • it receives back a formatted text with the result, and a data set containing the data for the Location Pickers in the page.
  • A dataset is linked to each formatted text entry, so that when picked, the correponding dataset part is loaded into the Location Picker it is destined for
  • When a result is picked:
  • the dataset on the registered Location Pickers is set by the Location active search Wiget
  • the user input is kept as typed
  • the keyboard is hidden and the focus moves away (Not sure if it is nessary on android to focus on something else)

    Class Model in pseudocode:

class LocationPicker:
   int picker_level // root =0, child = 1, child of child = 2 e.t.c
   LocationPickerDataset dataset   
   LocationActiveSearch active_search //Active search which needs to be announced when the user erases part of the search
   // Note that the link to active_search might be solved more elegantly by using Callbacks

   LocationPicker  child // This is not mandatory
   LocationPicker parent // This is mandatory, but can be null = Root of the tree. It's value can be deduced 
                                   //from the dataset
class LocationActiveSearch:
   List<LocationPicker> location_pickers // A list of the location pickers which get input from this LocationActiveSearch
   int search_delay; // delay in milliseconds to send a query after the search_text has changed
   String search_text //  Search text as input from the user. This can differ from current_dataset_search_text which will be set delayed, upon receiving a search response from the server
   String current_dataset_search_text : //Current search text for which the dataset is available
   List<LocationPickerDataset> current_dataset // List of  datasets for each possible choice corresponding to formatted_search_result
   List<FormattedString> search_results // List of entries to be offered as choice for the user to pick.
   LocationPicker location_picker // Location picker to set the LocationPickerDataset for a picked result
class LocationBit
   String name
   Location location // optional
   int radius // optional, radius in meters for which this location bit is still valid
class LocationPickerDataset
   List<List<LocationBit>> levels // location bits  by picker level
   Optional<boolean> is_complete // set to true if the location definition of the last picker in dataset is complete
   Optional<int> fixed_location_bits_count //  if 2 than the first 2 location bits are fixed.
    // Note that this can actually exceed the limits of a picker level.

class LocationActiveSearchRequest:
   String user_input
   LocationPickerDataset  current_data_set
   Position current_position // see http://www.w3schools.com/html/html5_geolocation.asp
                             // regarding getCurrentPosition() return data structure 
   int max_results // Maximum number of results 
class Position:
   // This class is analogous to the return Object getCurrentPosition() 
   // as defined Here http://www.w3schools.com/html/html5_geolocation.asp
   Coordinates coords
   int timestamp // ms since 1.1.1970
class Coordinates:
    //see Position description
    float latitude
    float longitude
    float accuracy
    float altitude
    float altitude_accuracy
    float heading
    float speed
class LocationSearchUpdate
  String query
  List<LocationQueryResultSection> result_sections  // the sections to be displayed in the result popup
class LocationQueryResultSection
  String name // Name of the result section
  List<LocationPickerDataset> result_datasets
  List<FormattedString> formatted_results // corresponds with result_datasets

Operation mode:

Both the LocationPicker and the LocationActiveSearch operate on and with LocationPickerDataset Objects.

Sequences of execution model:

Let's look at what happens from loading time to the completion of a Location specification:

• App initialization on startup or Location Change
  1. LocationActiveSearch dispatches a search request with an empty user string, and the current Location if available. This is done when no previous Location is stored, or when the current Location differs enough to invalidate at least one of the LocationBitDataset components in the current LocationPickerDataset
  2. The Server responds with the current location`s ( if available) dataset. In case no location information is available a response might still contain data, if the service is offered in a single city,continent or planet :)
  3. The LocationPickerDataset is persistently stored on the device as the current location if no other dataset exists with a common prefix (see picking current LocationPickerDataset)
  4. The LocationPickerDataset from the Result is set on the LocationPicker's
     • it is enough to set the dataset on the root LocationPicker as the same dataset is referenced by all child LocationPicker instances
  5. If the Profile page is displayed the LocationPicker shall update to display the current LocationPickerDataset
• Active Search Sequence on profile page
  1. After App initialization a LocationPickerDataset object is preconfigured which represents the current location. This object is loaded as the current location of the LocationPicker
  2. The user can now isert text into the active search
  3. On any modification an active search element is displayed in the search window (3 dots, rotating circle e.t.c)
  4. After LocationActiveSearch.search_delay a search REQUEST is sent (asynchronously)
  5. Upon receiving a result the LocationActiveSearch the result is discarded if:
     • another LocationActiveSearch is available for a later request
     • the current 'LocationPicker.dataset' differs from the dataset used in the request
  6. next LocationActiveSearch.search_text is compared to the LocationSearchUpdate.query string
     • if LocationActiveSearch.search_text == LocationSearchUpdate.query
     • deactivate active search element
     • display LocationSearchUpdate.formatted_result contents
     • if LocationActiveSearch.search_text.contains(LocationSearchUpdate.query) or LocationSearchUpdate.query.contains(LocationActiveSearch.search_text):
     • display LocationSearchUpdate.formatted_result contents
     • else:
     • discard resultset
  7. The comparision in 5. is also done on any LocationSearchUpdate.query with the currently displayed LocationActiveSearch.
     • If LocationSearchUpdate.query is no longer valid the search results are removed immediately. Only the active search indicator (moving circle) remains.
• Active search location user pick
  1. The User picks one of the results being displayed as search results
  2. The LocationActiveSearch sets the picked LocationPickerDataset as the dataset of the root LocationPicker
  3. Each LocationPicker in the hierarchy
     • updates it's LocationBit elements according to the new LocationPickerDataset
     • lets the Validators update their status according to the new LocationPickerDataset
• Location Picker LocationBit erasure:
  1. The LocationPickerDataset of the LocationPicker is modified. All Entries corresponding to the selected LocationBit LBx and all other entries corresponding to any LNy with x>=y will be deleted
  2. The LocationPickers affected are updated
  3. An active search is started with the current LocationSearchUpdate.query and the modified LocationPickerDataset

[paulbalomiri]

Note that a correction has been made: The CORRECT version as updated in the ticket description is :

class Dataset
   List<List<LocationBitDataset>> location_bits_content_by_picker_level

Whereas previously it was

class Dataset
   List<List<String>> location_bits_content_by_picker_level