GSoC 2012 - HTML Form Entry Module Enhancements

Owned by Ishara Premadasa
Last updated: Jan 06, 2017 by Hillary Bagiire
6 min read

Introduction

The HTML Form Entry module allows anyone with basic HTML skills and a knowledge of the OpenMRS system to create forms to enter and edit patient data within the system. It allow users to write forms using HTML combined with a set of special tags that reference different aspects of the OpenMRS data model.

The tags provided by the module has been steady expanding with each new release, but there is consistently a backlog of new tags and improvements to existing tags that the community has requested. This main objective of this GSoC project is taking on some of these suggestions into action.

The following are the improved features/new features that has been added into the Html Form Entry with this project.

Implementation

1. HTML-72 : Add autocomplete search functionality to encounter provider and encounter location widgets in HTML Form Entry

Encounter location and provider have been implemented by having two dedicated widgets for each such as, LocationWidget (for <encounterLocation>) and PersonStubWidget (for <encounterProvider>) tags. In addition to that there is another encounter provider is introduced with htmlformentry 1.9 onwards which too uses a dedicated widget named ProviderWidget with <encounterProviderAndRole> tag. The intention of the task is replace the dedicated  widgets for location, provider etc. and implement a common auto complete mechanism over the Html Form Entry module by just using AutoCompleteWidget and the DropDownWidget for the fields. In that case when a user needs to add auto complete functionality into any other field, it can be easily done by using the new, generalized AutoCompleteWidget.

  • There are two different auto complete mechanisms are used, one is with a pre-populated list and the other is using an Ajax search. Since these follow different approaches two seperate auto complete widgets are kept in the module named ConceptSearchAutocompleteWiget (for Ajax search) and AutocompleteWidget (for general, predefined option search).
  • AutocompleteWidget is converted and implemented into a SingleOptionWidget and generalized to accept an Option list of any type, i.e. Location, Provider etc.
  • Auto complete functionality is added into <encounterLocation> and <encounterProvider> using this AutocompleteWidget
  • LocationWidget and ProviderWidget in the module is replaced with the new AutocompleteWidget or a default DropDownWidget, hence they have been deprecated for future occurrences.

 In addition to that all the previous attributes and the javascript functions which worked with <encounterLocation> and <encounterProvider> tags will be working with the new autocomplete too.

Along with this task some of the remained bugs in the existing obs autocomplete functionality listed as, HTML-343, HTML-323 and HTML-217 have been fixed too.

2. HTML-249 : Tag to restrict all (or part of) an HTML Form by role

This feature is concerned to be implemented in a way that, some user with a particular role can be restricted from either viewing a certain HTML form (or a section in the form) by using the <restrictByRole> tag. The tag comes with two attributes as "include" and "exclude" where you can mention the names of the roles for whom you want to include or exclude the form restriction.

As an example if you don't need to make a certain table in your HTML form to be viewable to a Person which has "Data Manager" role assigned to him/her, you form description would be as follows,

<restrictByRole exclude="Data Manager">

<table><tr>

<obs conceptId = "6100" labelText="Restricted for Data Manager">

</restrictByRole>

</tr></table>

So this table would not be shown to any person with the 'Data Manager' role but only to the users who doesn't have that role. In the same way this can be used with "include" attribute, in where the corresponding section would only be not restricted to the mentioned role.

An example form would be like, as,

<restrictByRole include="System Developer">

<table><tr>

<obs conceptId = "6100" labelText="Not Restricted for System Developer">

</restrictByRole>

</tr></table

3. HTML-247 : Exit from care tag

A new tag to the module tagbase which is used to record the scenario where a patient exits care. It operates in a similar manner to the exit from care functionality on the patient dashboard, providing a date field  and a reason dropdown to the user. Exiting a patient from care is not mandatory, however once the fields are filled out and submitted for a certain patient, the exit can't be undone, hence the fields can't be set back to empty. However it is possible to edit the date and reason fields.The possible reasons for exiting care are specified by setting the global property concept.reasonExitedCare. This should point to a question concept; the associated answer concepts will be used to populate the reason dropdown presented to the user.

  • To exit a patient from care, the date field should be set to the date of the patient's exit and the reason dropdown set to the reason for the patient's exit selected from the list of given reasons.

If the patient is dead, the tag can be also used to mark a patient's death, by recording the cause of death in the additional dropdown that pops up. The user needs to select the reason dropdown answer as "Patient Died", then a new dropdown will be visible for the user to enter the 'Cause of Death'. The possible causes for patient's death are specified by setting the global property concept.causeOfDeath. This should point to a question concept; the associated answer concepts will be used to populate the cause of death dropdown presented to the user.

  • To mark a patient as dead, the reason field should be set to Patient Died and the cause of death dropdown set to the cause for the death selected from the list of given causes.

if the exact cause is not given in the cause dropdown,  select the 'Cause of Death' dropdown answer as "Other Non-coded", as there will be another text field visible to manually enter the reason for the death. Here the user can type any of the reason,description etc. which caused the patient's death. 

Once the cause of death and other reason text fields are filled out and submitted for a certain patient, the death obs can't be undone. However it is possible to change the reason for exit field back to an answer other than "Patient Died", so the exit observation can be edited back. Then it will not display the death fields' entries but the death obs still exists. It is also possible to edit the cause of death and other reason fields too.

Screenshots

1. Autocomplete Functionality in <encounterProvider> and <encounterLocation> tags
The new autocomplete fields in Encounter Provider and Location

A form with <restrictByRole> tag
A form with <exitfromCare> tag
1. Select a valid reason and a date for the exit entry
2. If the patient is dead, select a cause for the death from the additional dropdown
3. If the cause for the death is not given, manually enter it in the text field

4. This is how the exit and death entries will be shown in the patient dashboard

Resources

The mid-term video demonstration of the project:

http://www.youtube.com/watch?v=qU0ld32ha88

The final video demonstration of the project:

http://www.youtube.com/watch?v=u6pdK1J1oxk

The mid-term presentation of the project:

https://openmrs.atlassian.net/wiki/download/attachments/22290283/gsoc+presentation2_ishara.pdf

Module documentation with the new features:

https://openmrs.atlassian.net/wiki/display/docs/HTML+Form+Entry+Module+HTML+Reference

About

This project of HTML Form Entry Module enhancements was completed by Ishara Premadasa under the guidance of Mark Goodrich for Google Summer of Code 2012.