Building > Quick Guides > Forms > Form Inputs
Data accessible from within CHT forms
contact-summary.templated.js
Customizing the fields, cards, and actions on profile pages
Contact profile pages display basic information about the contact along with their history and upcoming tasks. A contact’s profile page is defined by the Fields, Cards, and Care Guides available.
Helper variables and functions for the contact summary can be defined in contact-summary-extras.js. There are several variables available to inspect to generate the summary information:
| Variable | Description |
|---|---|
contact | The currently selected contact. This has minimal stubs for the contact.parent, so if you want to refer to a property on the parent use lineage below. |
reports | An array of reports for the contact or for any of the contact’s person children. Note that if the contact has more than 500 reports, only the 500 with the latest reported_date values will be provided. Prior to version 4.7.0, only 50 reports were provided. |
lineage | An array of the contact’s parents (2.13+), eg lineage[0] is the parent, lineage[1] is the grandparent, etc. Each lineage entry has full information for the contact, so you can use lineage[1].contact.phone. lineage will include only those contacts which are visible to the logged in profile |
targetDoc | Doc with target document of the contact, hydrated with the config information of every target it contains a value for. If there is no target document available (for example when viewing a contact that does not upload targets), this value will be undefined. This value might also be undefined if the contact has not yet synced the current target document. Added in 3.9.0. |
uhcStats | Object containing UHC stats information. Added in v3.12.0 |
uhcStats.uhcInterval | Object containing the start and end date of UHC reporting period, it is calculated from the uhc.visit_count.month_start_date defined in the app settings. |
uhcStats.uhcInterval.start | Timestamp, start date of the UHC reporting period. |
uhcStats.uhcInterval.end | Timestamp, end date of the UHC reporting period. |
uhcStats.homeVisits | Object containing the contact’s home visits stats. The contact’s type should have count_visits enabled and the UHC visit count settings should be defined, additionally this information is only available for users that have can_view_uhc_stats permission and that are not System Administrators. |
uhcStats.homeVisits.lastVisitedDate | Timestamp, date of contact’s last home visit. |
uhcStats.homeVisits.count | Number of contact’s home visits in the current reporting interval. |
uhcStats.homeVisits.countGoal | Number, home visits goal, defined in the UHC visit count settings. |
cht | Object containing the CHT API for contact summary, targets and tasks. Added in v3.12.0 |
CHT API
Introduced in v3.12.0
Provides CHT-Core Framework’s functions to contact summary, targets and tasks. The API is available in the cht reserved variable under the v1 version.
| Function | Arguments | Description |
|---|---|---|
| hasPermissions(permissions, userRoles, chtPermissionsSettings) | permissions: String or array of permission name(s).userRoles: (Optional) Array of user roles. Default to the current logged in user.chtPermissionsSettings: (Optional) Object of configured permissions in CHT-Core’s settings. Default to the current instance’s configured permissions. | Returns true if the user has the permission(s), otherwise returns false. |
| hasAnyPermission(permissionsGroups, userRoles, chtPermissionsSettings) | permissionsGroups: Array of groups of permission name(s).userRoles: (Optional) Array of user roles. Default to the current logged in user.chtPermissionsSettings: (Optional) Object of configured permissions in CHT-Core’s settings. Default to the current instance’s configured permissions. | Returns true if the user has all the permissions of any of the provided groups, otherwise returns false. |
| getExtensionLib(name) | name: String of script name | Returns an executable function identified by the given name configured as extension-libs. |
| analytics.getTargetDocs() | Returns three target documents of the contact, calculated for the last three reporting intervals, including the current one. When viewing one of the current logged in user’s associated facilities, returns the target documents for the contact associated with the current logged in user. Returns an empty array if no target documents are found (for example when viewing a contact that does not upload targets). Introduced in v4.11.0 |
CHT API’s code samples
const canEdit = cht.v1.hasPermissions('can_edit');
const canManagePlaces = cht.v1.hasPermissions(['can_create_places', 'can_update_places']);
const hasAnyGroup = cht.v1.hasAnyPermission([
['can_view_messages', 'can_view_message_action'],
['can_view_reports', 'can_verify_reports']
]);
const averageFn = cht.v1.getExtensionLib('average.js');
const targetDocs = cht.v1.analytics.getTargetDocs();
Contact Summary
Each field that can be shown on a contact’s profile is defined as an object in the fields array of contact-summary.templated.js. The properties for each object determine how and when the field is shown.
contact-summary.templated.js .fields[]
| property | type | description | required |
|---|---|---|---|
label | string | A translation key which is shown with the field. | yes |
icon | string | The name of the icon to display beside this field, as defined through the Configuration > Icons page. | no |
value | string | The value shown for the field. | yes |
filter | string | The display filter to apply to the value, eg: { value: '2005-10-09', filter: 'age' } will render as “11 years”. Common filters are: age, phone, weeksPregnant, relativeDate, relativeDay, fullDate, simpleDate, simpleDateTime, lineage, resourceIcon, translate. For the complete list of filters, and more details on what each does, check out the code in webapp/src/ts/pipes dir. | no |
width | integer | The horizontal space for the field. Common values are 12 for full width, 6 for half width, or 3 for quarter width. Default 12. | no |
translate | boolean | Whether or not to translate the value. Defaults to false. | no |
context | object | When translate: true and value uses translation variables, this value should provide the translation variables. | no |
appliesIf | function() or boolean | Return true if the field should be shown. | no |
appliesToType | string[] | Filters the contacts for which appliesIf will be evaluated. For example, ['person'] or ['clinic', 'health_center']. It defaults to all types if it is not defined. | no |
Condition Cards
Each condition card is defined as a card object in the cards array of contact-summary.templated.js. The properties for each object determine how and when the card and its fields are shown.
contact-summary.templated.js .cards[]
| property | type | description | required |
|---|---|---|---|
label | translation key | Label on top of card. | yes |
appliesToType | string[] | A filter, so appliesIf is called only if the contact’s type matches one or more of the elements. For example, ['person']. Please, note that ['report'] is also allowed to create a report card. But, you cannot use it in conjunction with a contact’s type. It defaults to all types if it is not defined. | no |
appliesIf | function(report) or boolean | Return true if the field should be shown. | no |
modifyContext | function(context, report) | Used to modify or add data which is passed as input to forms filled from the contact page. | no |
fields | Array[] of fields | The content of the card. | yes |
fields[n].appliesIf | boolean or function(report) | Same as Fields.appliesIf above. | |
fields[n].label | string or function(report) | Label shown with the field. | yes |
fields[n].icon | string or function(report) | The name of the icon to display beside this field, as defined through the Configuration > Icons page. | no |
fields[n].value | string or function(report) | The value shown for the field. | yes |
fields[n].filter | string or function(report) | The display filter to apply to the value, eg: { value: '2005-10-09', filter: 'age' } will render as “11 years”. Common filters are: age, phone, weeksPregnant, relativeDate, relativeDay, fullDate, simpleDate, simpleDateTime, lineage, resourceIcon, translate. For the complete list of filters, and more details on what each does, check out the code in webapp/src/ts/pipes dir. | no |
fields[n].width | integer or function(report) | The horizontal space for the field. Common values are 12 for full width, 6 for half width, or 3 for quarter width. Default 12. | no |
fields[n].translate | boolean or function(report) | Whether or not to translate the value. Defaults to false. | no |
fields[n].context | object | When translate: true and value uses translation variables, this value should provide the translation variables. Only supports properties count and total on cards. | no |
Care Guides
Each care guide accessible from a contact profile is defined as an App Form. Context information can be provided to forms via the context object of contact-summary.templated.js.
To show an App Form on a contact’s profile, the form’s expression field in its properties file must evaluate to true for that contact. The context information from the profile is accessible as the variable summary.
The context data is also available directly within the app forms’ XForm calculations, as instance('contact-summary')/context/${variable}. For instance if context.is_pregnant is used in the contact summary, it can be accessed in an XForm field’s calculation as instance('contact-summary')/context/is_pregnant. Note that these fields are not available when editing a previously completed form, or when accessing the form from outside of the profile page.
Code samples
The following samples show how fields, cards, and care guide context comes together in the contact-summary.templated.js file.
contact-summary.templated.js
module.exports = {
context: {
use_cases: {
anc: isCoveredByUseCaseInLineage(lineage, 'anc'),
pnc: isCoveredByUseCaseInLineage(lineage, 'pnc'),
},
},
fields: [
{ appliesToType: 'person', label: 'patient_id', value: contact.patient_id, width: 4 },
{ appliesToType: 'person', label: 'contact.age', value: contact.date_of_birth, width: 4, filter: 'age' },
{ appliesToType: 'person', label: 'contact.parent', value: lineage, filter: 'lineage' },
{ appliesToType: '!person', appliesIf: function() { return contact.parent && lineage[0]; }, label: 'contact.parent', value: lineage, filter: 'lineage' },
],
cards: [
{
label: 'contact.profile.pregnancy',
appliesToType: 'report',
appliesIf: extras.isActivePregnancy,
fields: [
{
label: 'contact.profile.edd',
value: function(report) { return report.fields.edd_8601; },
filter: 'relativeDay',
width: 12
},
{
label: 'contact.profile.visit',
value: 'contact.profile.visits.of',
translate: true,
context: {
count: function(report) { return extras.getSubsequentVisits(report).length; },
total: 4,
},
width: 6,
},
{
label: 'contact.profile.risk.title',
value: function(report) { return extras.isHighRiskPregnancy(report) ? 'high' : 'normal'; },
translate: true,
width: 5,
icon: function(report) { return extras.isHighRiskPregnancy(report) ? 'risk' : ''; },
},
],
modifyContext: function(ctx) {
ctx.pregnant = true; // don't show Create Pregnancy Report button
},
},
],
};
contact-summary-extras.js
module.exports = {
isActivePregnancy : function(report) {
// ...
},
isCoveredByUseCaseInLineage: function(lineage, usecase) {
// ...
},
isHighRiskPregnancy: function(report) {
// ...
},
getSubsequentVisits: function(report) {
// ...
},
};
Build
To update the Contact profiles for an app, changes must be compiled into app-settings, then uploaded.
cht --local compile-app-settings backup-app-settings upload-app-settings
Related Content
Feedback
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.
Last modified 06.11.2024: Migrate contact summary (#1688) (56e552f3)