Managing Forms and Form Fields

Summary

Forms shown within the Android client app, such as the encounter and PCR form, are defined on and retrieved from the OpenMRS server. This document describes how to manage forms and form fields, both in OpenMRS and in the client app.

Form Definitions and XForms

Form definitions are managed on the server from the administration interface at http://{server:port}/openmrs/admin/forms/form.list

We use form definitions stored on the server for two things at the moment. The first is generating XForms for entering new data.

ODK Collect dynamically generates the client UI for each form from a form definition expressed in XML using XForms.

The XForms XML is generated on the fly on the server by combining several OpenMRS data model elements:

• Forms (forms, form_fields) define the group titles and the question order within each group.
• Concepts (concepts, concept_names, etc.) define the questions and possible answers.

Our OpenMRS forms to generate xforms have the following names:

• Clinical Observation: The main observation form, shown when you tap the pencil icon on a patient chart.
• Test results: The Ebola lab test results form, shown when you tap the flask icon on a patient chart. New Patient: Currently unused.

We also use forms for configuring the patient chart UI. The server controls what data is synchronized with the client, and what order it is displayed in. For this purpose we have two forms:

• Chart top section: This form specifies concepts that should be synchronized to the client. These are usually observations displayed in the customized "top" section of the chart
• Chart display order: This form specifies the observations and ordering for the lower lines of the patient chart.

If a observation concept is not in one of these two forms, then it will not be synchronized to the client, and so it won't be displayed. So any new question should be added to one of these forms in order to be displayed.

Form UI strings

Most of the form strings (questions and answers) are the names of concepts. Each concept in the dictionary may have any of the following for each locale:

• a fully specified name
• a short name
• other names (called synonyms)
• a description

Within OpenMRS we do not change any of the names except in our own special Locale variant (described below). Within this variant we only use the fully specified name for the Xform. The code is all in ClientConceptNamer.java, and uses the OpenMRS concept of preferred name for a given locale.

The en_GB_client locale

We use a special locale with the locale code en_GB_client (see ClientConceptNamer.java) to let us freely customize the strings shown in the UI (in OpenMRS > Administration > Manage Concepts). We generally do not edit strings in the en locale, to avoid conflicts with the canonical, externally managed concept dictionary. If there is no name in the en_GB_client locale for a given concept, the UI falls back to using the name in the en locale.

Magic XForm Section Strings

Our forms such as Clinical Observation which get turned into xforms are structured to have question concepts within sections. The sections have FieldType of Section in the administration interface. By adding extra strings to the section names you can affect the client behavior for displaying the section The form field Description is used as a header at the top of the section in the form, unless ...

• [invisible] in Field name for a section tells the client not to display the name of the section in the form itself, allowing two sections to invisibly join together
• [binary] in Field name for a section tells the client to display YES|NO|UNDEFINED choices in that section as on off buttons, rather than the normal radio buttons

Viewing a Form Definition

To view or edit the definition of a form in OpenMRS:

1. Log into your development OpenMRS server

2. Click Administration

3. Click Manage Forms

4. Click on the form to view/edit

Most changes will be made in the Schema Design section, which defines form fields, organized by section. More information about individual operations is provided in the sections that follow.

Editing a Field

To edit a field (or section) from schema design, double-click the desired field. This will bring up a window with fields described below, which can be edited as necessary.

Fields with type Section represent groups of related fields. For these fields:

• Field Name is only used internally and to define some custom UI (see Managing Forms and Form Fields#Magic XForm Section Strings)
• Description is the text displayed as a section header in the client (note: this text is not localized, so using the description in this manner should be phased out)
• Field Number is used to sort the sections when displayed; for consistency, this should match the position of the section in the form

Most individual fields will have the type Concept, meaning that the field is a representation of an OpenMRS concept. For these fields:

• Field Name is only used internally, but typically matches the concept name for consistency
• Description is only used internally
• Concept defines the concept that the field maps to; this is where most of the definition of a field originates. To change or add the concept, see Managing Forms and Form Fields#Modifying-a-Concept or Managing Forms and Form Fields#Adding a Concept.
• Default Value should generally be left blank, but allows for a default value to be specified
• Required, if set, will make the field required. The client respects this field and will show error messages whenever a required field is left blank.

Adding a Field

To add a field, right-click on the section that will contain the field and click Create. Then fill out the fields as described in Managing Forms and Form Fields#Editing-a-Field and click Save. If necessary, the field can be repositioned after creation by dragging the field to a different position or section.

Adding a Section

To add a new section, right-click on an existing section and click Create. Then fill out the fields as described in Managing Forms and Form Fields#Editing a Field and click Save.

The new section will be incorrectly positioned within an existing section. To fix this, drag the new section to the proper position. Afterwards, ensure that each section has the correct field number.

Modifying a Concept

Modifying concepts should be kept to a minimum unless the concept is a nonstandard concept or you are planning on contributing the concept changes back to the concept dictionaries that contain it. Otherwise, modifying concepts can create inconsistencies with other applications and data sources.

To modify a concept:

1. Log into your development OpenMRS server

2. Click Administration

3. Click View Concept Dictionary

4. Search for the concept to edit, by name or id

5. Click the desired concept

6. Click Edit

7. Make changes as necessary. For detailed information on concept fields, see Concept Dictionary Basics.

8. Click Save Concept

Adding a Concept

New concepts should be added carefully, conforming to the best practices for concepts defined by OpenMRS.

With that in mind, to add a concept:

1. Log into your development OpenMRS server

2. Click Administration

3. Click View Concept Dictionary

4. Click Add new Concept

5. Fill out fields as necessary. For detailed information on concept fields, see Concept Dictionary Basics.

6. Click Save Concept

Custom Field UI

The client application currently looks for a number of hardcoded concept ids, which it applies custom display logic to. Over time, these customizations should be generalized so that they can be easily applied to more fields. For more information, see Modularization (Client Refactoring).

Contributing a Concept to a Concept Dictionary

New concepts should ideally be contributed back to a standard concept dictionary. For more information on contributing concepts externally, see Contributing New Concepts.