Support Address Hierarchy

(Note Oct 2021: This is needed for the PIH Mexico 3.x pilot. Screenshot attached.)

BA: ddesimone (for any requirements questions)

As a health care provider
I want to be able to record the patient's address in a quick and easy manner
So that I avoid typing mistakes and long registration process

Context

In continuation of MF-250 we would like to provide dropdown options for the address input fields in order to improve the user experience. To provide an intuitive way for the user to enter the address of a patient, we would like to add a search field to search for addresses across all levels (leveraging the Address Hierarchy module):

Upon click, the address input fields will be filled in with the selected data provided by the Address Hierarchy module.

Addresses are stored in form of a hierarchy where each entry is related to its higher level parent (example below): 

Place du Tertre is a Rue that belongs to 18ème Arrondissment, itself belonging to City Paris, itself in Département Ile de France, itself in Pays France

• Pays
  • Département
    • City
      • Arrondissement
        • Rue

 In scope

• addition of a 'search bar' to search across all levels as a shortcut to having to scroll through a dropdown
• on typing a list of dropdown options is shown (provided by the Address Hierarchy module)
• keep the ability to manually enter the field without searching in the Address Hierarchy

Out of scope

• ability to search by Level, and to narrow down the possible choices for the levels below.

Implementation Context

• The address input fields are specified by the Address Template (see MF-286)
• The values for the dropdown options are configured via a textfile in the the Address Hierarchy Module Administration
• Access to the Address Hierarchy data is provided via a RESTful Api by AddressHierarchyAjaxController.java
• The search endpoint to be used is one of

1. https://openmrs-spa.org/openmrs/module/addresshierarchy/ajax/getPossibleFullAddresses.form?separator=%7C&searchString=bo with separator=delimiter being the delimiter used so separate hierarchy levels in the returned address strings and searchString=value being the query parameter specifying the search value entered by the user
2. https://openmrs-spa.org/openmrs/module/addresshierarchy/ajax/getPossibleAddressHierarchyEntriesWithParents.form?addressField=country&limit=20&searchString=cam where searchString=value is the query parameter specifying the search value entered by the user and addressField=field is the query parameter specifying which hierarchy level will be searched.