Input data available in forms

CHT forms have access to varying amounts of input data depending on the type of form and its source.

contact forms

Available data:

• initial contact data
• inputs data for user
• Contact data via contact selector

Initial contact data in contact forms

Create forms

Forms for adding contacts have access to a small group of fields contained in a top-level group that is named for the contact_type id of the contact being added (so person, clinic, etc). (This is the same group used to create the contact document when the form is completed.)

Edit forms

Forms for editing contacts have access to all the contact’s current data. These fields are contained in a top-level group that is named for the contact_type id of the contact being added (so person, clinic, etc). If fields in the top-level group are edited by the form, these changes will be saved to the contact’s doc.

In addition, the contact’s parent data is hydrated so that the form has access to the data stored on the parent contact doc in the parent group.

app forms

Available data:

• inputs data for source
• inputs data for contact
• contact-summary data
• inputs data from task
• inputs data for user
• Contact data via contact selector

Form source

If a form is created from the “People” tab, inputs/source will be set to “contact”. If a form is created from a task, inputs/source will be set to “task”.

inputs data for contact in app forms

app forms with a contact in context have access to that contact’s data in the inputs/contact group.

The contact group contains all the fields from the doc of the contact in context. If a place is in context, the primary person for that place will be hydrated in the inputs/contact/contact group. Alternatively, when a person is in context, the parent place for the person will be hydrated in inputs/contact/parent.

contact-summary data

app forms with a contact in context can access the contact-summary data associated with the contact. This is done by referencing an instance named contact-summary. E.g. instance('contact-summary')/context/${variable}. See the reference documentation for more information.

inputs data from task

app forms created via a task have access to any data supplied by the task in the inputs group.

user data

Both app and contact forms can access the current user’s data at inputs/user. The data provided is simply the user-settings doc for the user (e.g. org.couchdb.user:username) plus an additional language field that contains the user’s currently selected language code.

Example of saving user data as metadata on a report

Loading the user’s contact data

While the inputs/user group does not contain the user’s contact data, it does contain the user’s contact_id which can be used to load the contact doc via a contact selector.

Contact selector

Using a contact selector allows you to load data from the selected contact (person or place). The contact’s id can be provided by the form or the user can search for an existing contact.

To select a contact in a form, create a field with the type string and set the appearance to select-contact type-{{contact_type_1}} type-{{contact_type_2}} .... Setting multiple contact_type ids allows the user to search among multiple types of contacts. If no contact type appearance is specified then all contact types will be queried when searching.

Searching for a contact

When a contact selector question is visible in a form, the user can search for a contact by typing in the search box.

A value can be pre-selected for the search box via a calculate expression. By default, the user can change the selected value, but this can be prevented by setting read_only = true.

Loading descendants of the current contact

Use the appearance descendant-of-current-contact to load the current contact’s descendants when opening an app form or contact form from the “People” tab.

Loading additional contact data

Additional data about the contact can be loaded by adding fields to the same group as the contact selector. The field name must match the name of a field on the contact doc. The data will be loaded when the contact is selected and will overwrite any existing data in the field.

Loading contact data for use in other expressions

One powerful way to use the contact selector is to automatically load data about an existing contact for usage in various expressions within the form. This can be done with a combination of functionality we have already seen!

In the following example, we are loading the name of the current user from the associated contact doc:

Conditionally selecting/loading contact data for the current contact

As noted above, when opening an app form with a contact in context (e.g. when opening the form from the “People” tab), the contact’s data will be available in the inputs/contact group. However, this data is not available when opening the form from the “Reports” tab since there is no contact in context.

A common pattern for enabling consistent form behavior in this case is to use a contact selector in the inputs/contact group and make the inputs group only relevant when the default source value is not overridden (the source field is populated with specific values when the form is opened from the “People” tab or from a task). With this pattern, the contact selector will only be visible when the form is opened from the “Reports” tab and the user can select the contact they want to report on. This will ensure that the inputs/contact data is always available regardless of how the form is opened.

Then, this contact data can be used to link the report created from the form to the person or place in context (or the person selected when opening the form). Getting the values for _id or patient_id and setting them to patient_id or patient_uuid on the final report will link that report to the contact. Then the report will be displayed on the contact’s summary page.

Related Content