Form Development

Owned by Grace Potma
Last updated: May 31, 2024 by Lucy Jemutai
5 min read

While developing forms, we use JSON to accomplish this. JSON is "self-describing" and easy to understand. Here, we shall look at the basic JSON syntax, their meanings and use case and a detail of the validations we add to the form engine to improve form behaviour.

Syntax expressions used in form schemas

  1. !== (Not equal to a certain value i.e. not the same as) Here the ! before any expression would declare the next expression as a not e.g. "include" would mean include this and that but when we do it as "!include" would mean not include or say do not include

  2. === (Is equal to a certain value i.e. same as)

  3. || (This means 'or' i.e. as well as)

  4. > (Is greater than)

  5. < (Is less than)

  6. >= (Is greater than or equal to)

  7. <= (Is less than or Equal to)

  8. && (AND)

Expressions

Expressions are used to add validations and behaviours to the form engine. We have two expressions while adding validations to questions/fields in the form engine i.e. hideWhenExpression is used to hide questions/fields and the failsWhenExpression added as part of the form validators for any questions that should throw an error within the form to avoid it from saving if the expressions are not met rightly usually used for dates.

Key points

  • hideWhenExpression is used to hide questions based on the desired behaviour to be implemented and used within the hide parameters.

    "hide": { "hideWhenExpression": "vaccineDose == null"" }

  • failsWhenExpression will throw an error on the form and fail it from saving and is used within the validators parameters.

    "validators": [ { "type": "js_expression", "failsWhenExpression": "isDateBefore(myValue,'2020-01-01') || myValue <= useFieldValue('vaccinationDate')" } ]

  • While adding concepts instead of question ids, they should be within single quotes. This is a requirement for any referred data value in JSON.

  • So as to complete the form for it to be able to save after adding validations and behaviours, we shall need to add the encounterType that is created from the backend at the end of the form as below:

    "processor": "EncounterFormProcessor", "uuid": "xxxx", "referencedForms": [], "encounterType": "5b37ce7a-c55e-4226-bdc8-5af04025a6de", "allowUnspecifiedAll": true

Below are selected scenarios to give a gist of how behaviours are used in the engine and can be used as a guide to achieve desired behaviours for specific questions within the said forms.

  1. isDateBefore(myValue, '1980-01-01') - This is used in a failsWhenExpression and would mean that if the date is before the value 1980-01-01, what ever question behaviour this expression is on should throw and error and not save. (isDateBefore is a REACT method and so can be used anywhere and everywhere in any form JSON while declaring this kind of validation)

  2. myValue > today() - This expression would imply that the expression should fail if at all the question date value is greater than today/current date (This also works for concepts or question ids and not only for date fields). For more context let us use this expression in this way:

This expression should fail if at all the date is less than or equal to "1/1/2020".

  1. isEmpty(testingLocation) - isEmpty is a REACT method that is used to check if a question is empty or values weren’t selected. This hideWhenExpression then would imply that the question with this behaviour in it should not open/display if at all the question with id testingLocation is empty or if no value was selected in it. We can also express this behaviour like below:

    Meaning that the question should not open if at all the question with id testingLocation doesn't have the value with concept 5995ebd5-11ae-47ca-ac12-bcb8c0117aec selected.

  2. !includes('vaccineAdministered','5622AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA') - !includes as well is a REACT method that takes care of the logic of “if a question does not include”. Therefore, for this scenario if the question with id vaccineAdministered doesn't include a selected value with concept 5622AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA, it should hide the field in which this hideWhenExpression behaviour is.

  3. vaccineDose == null - This means if a question with id vaccineDose has no values selected/is NULL, the current question in which this hideWhenExpression is should be hidden or not displayed. Instead of Null we can also put in a concept pointing to a given field e.g.

  4. myValue <= useFieldValue('vaccinationDate') - useFieldValue is a REACT method that uses a specified field value for the id provided to a given question. For this failsWhenExpressionthen means that the current question should fail or throw and error if the value is less than or equal to the value added by the user in the UI for the question with id vaccinationDate i.e. if the user entered the date ‘2021-03-09' for the vaccination Date question, the question in which this validator is should throw an error and fail to save if at all the date value of said question is less than or equal to 2021-03-09 .

 

Form Configuration

You will need to define the form validation rules using JSON expressions for each form element. Behaviors such as conditional visibility, error handling, and action triggers are configurable. Additionally, Test the form using the form-render to ensure validations and behaviors function as expected.

Example Validation Expression:

Launching Forms in the RFE

In the RFE, there is function is used to launch and view a form within the patient workspace. It serves the purpose of displaying forms for viewing purposes, such as reviewing previously entered data or accessing read-only versions of forms, in min/max workspace size, and includes associated data like encounterUuid and patientUuid. Additionally, it provides callbacks for form save and form mutation actions.

The function has parameters like the OHRIFormSchema includes essential information about the form's structure, fields, validations, and other configuration settings necessary for rendering and processing the form within the patient workspace.

When launching forms within the patient workspace. The RFE four distinct actions: add for adding new form entries, view for read-only form viewing, edit for modifying existing entries, and embedded-view specifically designed for viewing embedded forms within another form.

The Form Development in the OpenMRS React Form Engine provides a powerful toolset for creating and configuring forms. By leveraging JSON syntax, users can build customized forms tailored to medical record management workflows, improving data collection and usability within the OpenMRS platform.