Building > Reference > forms/
Forms: All the App forms, Contact forms, and Collect forms
CHT forms have access to varying amounts of input data depending on the type of form and its source.
contact
formsAvailable data:
contact
formsForms 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.)
type | name | label | hint |
---|---|---|---|
begin group | person | NO_LABEL | |
hidden | parent | Parent Id | Contains the doc id for the new contact’s parent contact doc. |
hidden | contact_type | Contact Type | The contact_type id of the contact. |
end group |
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.
type | name | label | hint |
---|---|---|---|
begin group | person | NO_LABEL | |
begin group | parent | Parent | Contains the data for the contact’s parent contact doc. |
hidden | name | Parent name | The name of the parent contact |
end group | parent | ||
end group |
app
formsAvailable data:
inputs
data for sourceinputs
data for contactcontact-summary
datainputs
data from taskinputs
data for userIf 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”.
source
field is also available at the top level (not nested in the inputs
group).inputs
data for contact in app
formsapp
forms with a contact in context have access to that contact’s data in the inputs/contact
group.
contact
group is also available at the top level (not nested in the inputs
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
dataapp
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.
contact
forms or in forms created from the “Reports” tab.inputs
data from taskapp
forms created via a task have access to any data supplied by the task in the inputs
group.
user
dataBoth 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.
user-settings
doc for the user is NOT the same as the CHT contact doc for the user.user
data as metadata on a reporttype | name | label | calculation |
---|---|---|---|
begin group | inputs | NO_LABEL | |
begin group | user | NO_LABEL | |
string | contact_id | User’s contact id | |
string | facility_id | Id for user’s facility | |
name | name | Username | |
end group | |||
end group | |||
calculate | created_by | Username that created report | ../inputs/user/name |
calculate | created_by_person_uuid | UUID that created report | ../inputs/user/contact_id |
calculate | created_by_place_uuid | Facility of user that created report | ../inputs/user/facility_id |
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.
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.
v3.9.x
and below, contacts must be selected by setting the field type to db:{{contact_type}}
and the appearance to db-object
(instead of using string
and select-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
.
type | name | label | appearance | calculate |
---|---|---|---|---|
string | person_id | Person ID | select-contact type-person | |
string | household_id | Household ID | select-contact type-clinic | ../inputs/contact/parent/_id |
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.
type | name | label | appearance |
---|---|---|---|
string | household_members | Household’s members | select-contact type-person descendant-of-current-contact |
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.
bind-id-only
is included in the appearance.type | name | label | appearance |
---|---|---|---|
begin group | selected_person | NO_LABEL | |
string | person_id | Person ID | select-contact type-person |
string | name | Name of selected person | |
end group | selected_person |
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:
type | name | label | appearance | calculate |
---|---|---|---|---|
begin group | inputs | NO_LABEL | ||
begin group | user | NO_LABEL | ||
hidden | contact_id | User’s Contact ID | ||
end group | user | |||
end group | inputs | |||
begin group | intro | NO_LABEL | field-list | |
begin group | current_user | NO_LABEL | ||
string | _id | User’s Contact ID | hidden select-contact type-person | ${contact_id} |
string | name | User’s name | hidden | |
end group | current_user | |||
calculate | user_name | Supervisor name | ../current_user/name | |
note | welcome | Welcome ${user_name}! | ||
end group | intro |
field-list
appearance). This is because there is a known issue that results in an empty page being added to the form when a top-level group had no visible questions.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.
type | name | label | appearance | calculate | relevant | default |
---|---|---|---|---|---|---|
begin group | inputs | NO_LABEL | field-list | ./source = ‘user’ | ||
hidden | source | Source | user | |||
begin group | contact | NO_LABEL | ||||
string | _id | Patient ID | select-contact type-person | |||
string | patient_id | Medic ID | hidden | |||
end group | contact | |||||
end group | inputs | |||||
calculate | patient_uuid | Patient UUID | ../contact/_id | |||
calculate | patient_id | Patient ID | ../contact/patient_id |
Forms: All the App forms, Contact forms, and Collect forms
Contact Pages: Customizing the fields, cards, and actions on profile pages
Demonstrates how to pass data into an application form via tasks
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.