Form Development Guidelines

UgandaEMR data collection is done through forms. There are two types of forms built using the HTML Form Entry module that can be added:
  1. 1.
    MoH HMIS forms - added the core aijar module
  2. 2.
    Custom IP forms - added to a custom module that depends on aijar
While the two form types are added to different locations the process of addition is similar and is outlined in the sections below.


The checklist below provides a guide in planning the form design
  1. 1.
    When is the form displayed
    • Gender restrictions - for males only or females only
    • Age restrictions - are there maximum or minimum ages
    • Service points - does the form apply to specific or all service points
    • Encounter Types - what encounter type does the form data collect for
  2. 2.
    What is the form design
    • Single Encounter form - captures data for a single encounter say circumcision, HIV testing etc
    • Multiple Encounter form - capture information for a treatment regime and is usually broken up into two different forms:
      • Summary - data that is captured only once
      • Encounter - captures data on patient visits as they happen
    • Single Page Longitudinal Form - this is similar to the multiple encounter form and best when the individual encounter information is about 5 - 10 fields, and its important to see the whole longitudinal record as a whole
  3. 3.
    Form Naming - follows the HMIS or relevant IP naming style e.g., 078-IntegratedPostnatalRegister.xml for HMIS 078 Integrated Postnatal Register

Implementing Forms

Design Best Practices

These best practices are a guide and can be altered to best suit the form design and data collection needs
  1. 1.
    Usage of form controls
    • Radio buttons for yes/no options
    • Radio buttons for elements with up to 4 options
    • Drop down boxes for more than 4 elements
  2. 2.
    Form labels will be placed as follows:
    • Text fields and drop downs - to the top of the input
    • Radio buttons and check boxes - to the left of the input
  3. 3.
    Handling other options:
    • A text field will be provided
    • The text field will be disabled by default and enabled only when the other option is selected.
    • When the other option is deselected, the text field will be disabled and its contents removed.
  4. 4.
    Related data shall be grouped in sections that are grouped together and each section must have a title
  5. 5.
    Flow of controls will be from left-to-right, and elements will be designed to flow horizontally
  6. 6.
    There will be four columns of elements on each row of the form
  7. 7.
    For radio button groups and checkboxes with an Other specify text field:
    • The text field will be disabled by default and only enabled when the other option is selected
    • When the other option is unselected the text field will be cleared and disabled
  8. 8.
    Disabled controls shall always have a fade shade of 0.25
  9. 9.
  10. 10.
    For data forms with more than row, the rows will have alternate light and dark colors.
  11. 11.
    Where codes exist, both the code and description must be shown in the radio button, checkbox or select dropdown. NOTE: Use a hyphen to seperate the code from the description.

Bootstrap Styling Guidelines

  1. 1.
    When using the Bootstrap grid system use do not use the grid classes i.e, (xs,sm,md,lg) for column definitions. Use only defined column width e.g, (col-4, col-8)

Single Encounter Form

The form needs to have the following:
  1. 1.
    Metadata - the fields required in the htmlform tag are:
    • formName - the name of the form which is displayed in links
    • formDescription - shown in lists
    • formEncounterType - the uuid of the encounter type to which the form data belongs
    • formUuid - the uuid of the form which must be unique across all forms
    • fromShowIf - this is optional but contains any constraints that must be met at patient level for the form to be displayed for entry
    • formDisplayStyle - only allowed value is Standard
  2. 2.
    A sample tag for the SMC form is below:
    <htmlform formName="HMIS 035a Safe Male Circumcision Client Card" formDescription="Captures clients undergoing safe male circumcision" formEncounterType="244da86d-f80e-48fe-aba9-067f241905ee" formUuid="9d9193e7-b038-4c44-a7a3-830baa288565" formVersion="1.2" formAddMetadata="yes" formUILocation="patientDashboard.visitActions" formOrder="7" formIcon="icon-medkit" formShowIf="( || ! &amp;&amp; patient.person.gender=='M' &amp;&amp; patient.person.dead==false &amp;&amp; sessionLocation.uuid=='8f96e239-8586-4ec6-9375-04c6e19628ae'" formDisplayStyle="Standard" formLabel="SMC Client Card">
  3. 3.
    Required tags for each form are:
    • Encounter date - the date when the encounter happened code is: <encounterDate default="today" disallowMultipleEncountersOnDate="block"/>
    • Encounter provider - the person who provided the service at the health facility code is: <encounterProvider role="Provider" style="autocomplete"/>
    • Encounter location - the health location the code is: <encounterLocation default="629d78e9-93e5-43b0-ad8a-48313fd99117" order="629d78e9-93e5-43b0-ad8a-48313fd99117"/>

Summary Forms

The only difference between a summary form and other forms is that it can only be entered once, so there is custom javascript that needs to be added

Encounter Form

This is the same as a single encounter form