Forms

A form is a collection of fields classified through pages, sections and questions. These fields are rendered differently based on their associated question type and rendering. For example, a text field will behave differently from a dropdown.

Forms are described using JSON schemas that conform to the O3 standard JSON schema spec. This standard JSON schema ensures that schemas built using either the Angular or React form engines have parity. Below is an example of a form rendered using the Form Engine:

O3 ships a form builder frontend module that users can leverage to build forms of arbitrary complexity. These schemas can then be published for use in the Patient Chart to collect data.

Forms can be in any one of the following states:

• published - can be accessed in both the form builder and the Patient Chart.

• unpublished - can only be accessed in the form builder. The Patient Chart forms workspace only loads published forms.

• retired - cannot be accessed in either the form builder or the Patient Chart.

Properties of a form

A form schema comprises the following properties:

Additional form properties

Pages

A page is a collection of related sections. A typical page definition consists of a label, inlineRendering (optional) and a list of sections. The engine uses the page’s label to identify it from other pages; that being said, it’s mandatory to keep the page’s label unique. Below is an example of a form with one page and section. The section has 4 questions labelled:

Here's how this page definition gets rendered:

In practice, your form will likely have more than one page. You can cycle through the pages by infinitely scrolling or selecting the desired page from the left sidebar. Here's how a form with multiple pages would look like:

Open

Sections

A section is an element of a form schema that groups related questions. Sections will be rendered in "expanded mode" by default. Set isExpanded to false in the section definition if you want the section rendered in "collapsed mode".

Below is an example of a basic section:

Subforms

Forms can be broken up into smaller, distinct units that can be reused within other forms and even programme areas. Subforms also enable mixing encounter types. For example, the parent form can post to an Assessment encounter type, but an embedded form for lab requests can post to a Lab test encounter type, while providing a single user experience. Subforms can be defined through pages, this gives us the flexibility of arbitrary positioning subforms anywhere within the parent form.

The isSubform attribute explicitly tells the engine that this page is a subform. The subform property is a manifestation of the embedded form, it defines meta properties of the subform like the subform target intent, parent behaviour override(s) like the readonly behaviour and form namespace.

A page is used when defining a collection of related sections while a subform is used when embedding different form to the current form.

Questions

A question is the smallest unit of a form, and enables a single piece of data to be collected.

Question properties

Here's a reference of the various properties you can specify in a question definition:

Open

• label: The actual content of the question. This label is what gets rendered as the question label. If no label is specified, the "display" value of the concept is used (which is generally the preferred name for the concept in the current locale)

• type: Provides information of how the submission value will be processed. It helps the engine map the target submission handler to a field. Currently supported types include: obs | obsGroup | encounterLocation

  • obs: questions of this type will yield an observation as a submit-able.

  • obsGroup: questions of this type will yield an obs group as a submit-able.

  • encounterLocation: questions of this type will capture a location that will be associated to the current encounter.

• questionOptions: An object defining other properties of a question:

  • rendering: The field type of the question. Currently supported types include: select | text | date | number | checkbox | radio | repeating | group | content-switcher | encounter-location | textarea | toggle | fixed-value read more about supported types.

  • concept: The concept UUID or concept reference mapping in the format "source:term" (for example "CIEL:1234") of the backing concept for this field.

  • defaultValue: The default value to be associated to this question.

  • answers: An array of answers scoped to a question. An answer definition consists of a concept UUID or mapping and label pair. If no label is specified, the "display" value of the concept is used. Below is an example of answers to a Current HIV status question:

• questionInfo: A property that recieves a string containing additional information regarding the field. When hovered over, it displays a tooltip containing the information passed.

  { "questionInfo": "sample tooltip info for text" }

Open

• isHidden: A boolean value that determines field visibility. In most cases, this value is driven by hide expressions.

• hide: You can use this to define logic for hiding a question based on certain conditions. To do so, you provide a JavaScript expression that evaluates to a boolean value:

  { "hide": { "hideWhenExpression": "onArt!== 'a899b35c-1350-11df-a1f1-0026b9348838'" } // This logic hides the question with the `onArt` id if the value of its // concept does not match the supplied value }

• required: If set true, that form field is considered to be mandatory. Defaults to false.

• unspecified: If set true, the form engine will render a widget(as part of this field) that can be used to mark this field as unspecified. By default, a mandatory field can't pass validation without a valid value. However, think of a scenario where it’s almost impossible to provide a value eg. when filling out a form in retrospective where a value wasn’t collected on the paper form. For such scenarios, a required field can be marked as unspecified.

• validators: An array in which you provide validation logic for the specific question. Learn more about validators.

• behaviours: An array of supported behaviours. Learn more about form behaviours.

• isTransient The RFE supports the ability to make a form field transient. Making a field transient means that the data entered into the form is not saved permanently. This functionality can be easily integrated into the JSON format, as demonstrated below.

Components

There may be situations where you might want to separate commonly-used form logic into separate reusable bits. In such cases, you can structure that logic as a component form. Components can therefore be thought of as reusable forms that carry domain-specific information. Imagine a situation where you're creating many forms for use in a Point of Care setting. You might find that multiple forms might need to have sections for collecting pre-clinic Review information. This pre-clinic Review information could include details such as:

• Current HIV status

• Whether a visit was scheduled or not

• Reasons for a visit

• Current visit type

• Patient's insurance information

Now imagine having to define all of these sections and their accompanying questions in each of your forms. Components are the perfect tool for such situations.

Creating Components

To create a component, follow the same procedure of creating a form(opens in a new tab) with the exception being at the point of saving.

1. It is advisable to prefix the name of the component with component_. For example, if you're creating a component for pre-clinic review, you could name it component_pre-clinic-review.

2. From the dropdown of encounters, you MUST select the encounter type Component as shown below:
   
   

Open

After saving, the component will be available in the list of forms and you can filter forms if you only want to view saved components.

Open

The resulting component json will be as shown below;

Referencing Components

You can reference components that have already been saved in the system by adding it the referencedForms key to your json form.

Available visual options

• form : The alias of the referenced component form as defined in the referencedForms key

• page : The page label of the referenced component form

• section : The section label of the referenced component form to be displayed

• excludeQuestions : An array of question id(s) to be excluded from the referenced section of component form

Example

Below is the complete json form with 2 components referenced;