Address hierarchy support module

Background

Address Hierarchy Support is one of the important module needed for enhanced user experience and easier administration. OpenMRS implementations need a way to enter patient location through a hierarchical approach — e.g., select a district from a drop-down list, then pick a village from within the district, then a location within the village.

Goal

Create a module which will allow the admin from within OpenMRS to easily create a location and to define custom location hierarchies. And the user from within OpenMRS to easily create a patient details with the flowing location hierarchy.

Targets

I have edited this with the help of Ben's suggestion

• Create two new tables address_hierarchy_type and address_hierarchy_type_value. address_hierarchy_type is to store and maintain the hierarchy components and address_hierarchy_type_value is to store the hierarchy component values or simply locations.

• Editing the column names of the table person_address as shown below.

      address1 

      address2 

      city_village --> sublocation1

      state_province 

      postal_code 

      country 

      longitude 

      latitude 

      neighborhood_cell --> sublocation2

      county_district --> sublocation3

      township_division --> sublocation4

      subregion --> sublocation5

      region --> sublocation6

• Adding a page under the module which enables admin to create locations in a hierarchical order and the values are stored in address_hierarchy_type_value.

• Editing the newPatientForm.jsp and its dependencies for enabling users to create the patient's location hierarchically and the locations are saved in the person_address table.

• For a clear working picture of the module please see below.

Deliverables

• The code for the module page which allows admin to create locations interactively and saves the locations in the location_attribute_type_value table and the hierarchy components in the location_attribute_type table. This will be my delivery for the mid-term evaluation.

• The rest of the project i.e. Editing the newPatientForm.jsp and its dependencies will be done after the mid term which enables users to select the locations hierarchically.

Example

Overriding the default addressLayout.jsp

I had to override the existing addressLayout.jsp. At first I was very confused in how to do it so I discussed it with Daniel, Brian and I sent an mail to the dev list. Finally Ben gave me an wonderful example and using that I successfully overriden the default addressLayout.jsp. Actually I tried that before Ben sent me the example but by mistake I extended SimpleFormController for portlet instead of the servlet one. Finally Daniel noticed it and corrected it and I have successfully overridden it. I had to create my own controller since the controller which the portlets usually extends doesnt support formView. But I think I am wrong in the moduleApplicationContext.xml part which is given below. Must show that to Daniel and cross check it. Or if you find something wrong in that please let me so that I can correct it.

Here’s a screenshot:

So this is how it overrides.

This is how i modified my moduleApplicationContext.xml

<bean id="addresshierarchyUrlMapping" class="org.springframework.web.servlet.handler.SimpleUrlHandlerMapping">
    	<property name="mappings">
            <props>
  		<prop key="**/addressLayout.portlet">addressLayoutPortletController</prop>
	    </props>
	</property>
</bean>


<bean id="addressLayoutPortletController" class="org.openmrs.module.addresshierarchy.web.controller.AddressLayoutPortletController" >
	<property name="commandName"><value>addressLayout</value></property>
	<property name="commandClass"><value>org.openmrs.module.addresshierarchy.web.controller.AddressLayoutPortletController</value></property>
	<property name="formView"><value>/module/@MODULE_ID@/portlets/addressLayout</value></property>
	<property name="successView"><value>/module/@MODULE_ID@/portlets/addressLayout</value></property>
	</bean>

Still I am not done with the backend. I have few doubts hope I will finish it within this week.

But I do face a problem with this. Whenever newPatient form reloads with some validation errors my addressLayout.jsp is missing there.

If someone has solution or suggestion please feel free to drop it here.

User Guide

• Load and start the AddressHierarchy module.
• Default location types will

  Sub Location 1
  Sub Location 2
  Sub Location 3
  Sub Location 4
  Sub Location 5
  Sub Location 6
  Sub Location 7
  Sub Location 8
  Postal Code
  Longitude
  Latitude

• User can use the default ones or can rename as per their needs. User can edit it in Hierarchy Management link in the Administration page.
• User can now go to Address Hierarchy Tree link in the Administration page to create locations.
• Wait till the page loads. When the page loads completely user can start adding the location by Right clicking the "Start" and select "Add Location Component". A popup will appear.
• The Address Type is filled automatically and if user wishes he can change it.
• User can add as many as locations he needs in the space provided and click "Add".
• Locations are now added.
• If user wants to create locations under a particular location (Example: if user wants to add States under Country), Right Click on the particular country and select "Add Location Components" and add the states and click "Add".
• To rename a component just Right Click on it and select "Edit Location Component". A popup will appear just enter the name you need and click "Ok". The name will be changed immediately.
• If user wants to delete a location, just Right Click on the location type and select "Delete Location Component". A confirm popup will appear and click "Ok" to delete the location and "Cancel" to abort the deletion.
• When user creates a new patient record user will be given a drop down facility to select patient's location.
• User has to pick the locations one by one in the hierarchy order. If user does not finds the location (Example: A city is missing under the States) then user can use the text box adjacent to the Drop down box to fill it and continues by adding the other following components in the text boxes.
• When user views a patient record in the Demographics section the address of the patient is listed in the order of preference.
• If user wishes to edit the address, click on the "Edit this Patient" link in the same page.
• User will be given drop down boxes again. Now user clicks the top hierarchy component (Example: Country) select box

and selects "Load". 

• All the locations are loaded and user can pick it up one by one. If a location component is not found user can use the text box to add it and it sub locations.

• Example

Administration Page

Management Hierarchy Page

Hierarchy Tree Start.

Popup to add locations. Thick.jpg

Context menu or Right click menu for the tree.

Popup to change the name.

Confirmation alert.

New Patient form.

Patient Dashboard.

Patient Form

Comments & Suggestion

Feel free to drop your suggestions here

Looks good. Make sure you're looking at the addressLayout.jsp portlet. That is what is called from newPatientForm.jsp.

It appears you've come up with a functional module. Good job! Several suggestions in order of importance...

1. Don't let the new address hierarchy take over the system when viewing / editing existing addresses which were not entered in the hierarchy method. I went back to edit an existing address and it's not populated in the Demographics / Edit this Patient page.
2. There should be a way for the admin to decide which fields the hierarchy data goes into the database so they could match with existing data. For example in the order I setup, the old address state field ended up in the new address country field. Perhaps being able to change the order of the items in the Hierarchy Management screen could resolve this?
3. ) Not all fields will be needed by all locations. Perhaps the administrator should be able to enable/disable fields. For example, we don't need Sub Location 6, Sub Location 7, Sub Location 8, Postal Code, Longitude, or Latitude.
4. Remove the unnecessary step of clicking Load to populate the list. This happens when adding a new address on the Edit this Patient (not the short form).
5. It might be nice to somehow be able to search for items rather than select them from a drop-down. Some of fields could have more than 100 items, for example the locality field in our case.
6. Automatically populate higher fields when selecting a lower field. For example, let me select the city and automatically fill in the county, state and country, assuming the city was unique in the list.

This is just my $0.02. Keep up the good work! --Arbaughj 11:07, 4 September 2008 (EDT)