The Case List and Case Detail screens on CommCare Mobile allow mobile users to find and view data about a case on their mobile device, even when offline. This page provides an overview of how Case List and Case Detail screens are used, and explains in detail how to configure them.
Case List and Detail Overview
Case List: You can specify the case property columns that are displayed in the case list. Due to the limited screen space on a mobile phone, you typically want to only include two columns. The phones will also let you search over the case properties in the columns - it is sometimes useful to include an ID that the user can quickly type a search term or scan a barcode to find the case they are looking for. The case list can also be sorted and filtered, based on the state of the case.
Case Detail: The case detail screen appears after selecting a case from the case list. It usually includes more information than the case list and is helpful for checking if the user has selected the correct case and providing additional information. For example, the case list may just contain the mother's name - but the case detail will include the husband's name to help users check if they've selected the right mother. To prevent the need for scrolling the case detail screen, important properties should be listed at the top.
CommCare for Android Example
Configuring the Case List and Case Detail
The case list and case detail are configured at the menu level. Click on the name of the menu for which you want to configure the list and detail screens. Each is configured on its own tab:
Case List Configuration
On the Case List tab you can configure several different things:
- Properties to Display - select the properties you want to display in the list
- Filters - write an expression which restricts the cases that are seen in the list
- Sorting - allows for multi-level sorting of the list
- Parent Child Selection - forces the user to first select the parent case before a child case
You can see each of these options in the example below:
In the top section you can select the case properties that will be displayed in the list. We recommend you think about the size of your screen when choosing how many properties to include. For example, a java phone can only fit about 2 properties, while a tablet may be able to fit 3 or 4.
- Add a property - simply starting typing in the name of the property. It will automatically populate and you can choose it form the dropdown
- Add Display Text - this is the text that the user will see. Note that if your app is in multiple languages, you will need to save your text, and then change your view to the next language in order to type in the display text for other languages.
- Select a Format - by default all of your properties will be "plain" which has no special formatting. There are many other options which can be useful:
- Plain: The case property will be displayed as plain text.
- Date: The case property will be formatted as a date. You may select one of several options for formatting the date (for example, DD/MM/YYYY).
- Time Since or Until: this is a way of referencing a date but showing time until that date, or time since that date. Possible units of time ("measured as") include years, months, or days. The time since/until will be truncated and not rounded; for example if 1 month and 3 weeks have passed, that would show up as 1 month on the device, not 2 months.
- Phone Number: CommCare will provide functionality to call or send an SMS to the number stored in the case property.
- ID Mapping: This will allow you to provide a friendly or localized label for a value stored in the case property. For example, if you have a 'state' case property for a pregnant mother that stores 'pregnant', 'not_pregnant' or 'delivered', you may want to display 'Pregnant', 'Not Pregnant' and 'Delivered' in the case list or detail.
- Late Flag: If the specified case property is more than the specified number of dates in the past (i.e. it is late), then it will be flagged i.e. it will show up as a '*' in a narrow column in the case list view (and as a '*' in the case details view). If the case property is less than the specified number of dates in the past or it is in the future (i.e. it is not late), then it will show up as blank in the case list view and it will not show up at all in the case details view. If the specified case property is null/uninitialized, it will be treated as though it is late. If the late flag is the first column in the case list view, then the not late (un-'*'-ed) cases will all be displayed, followed by the late ('*'-ed) cases.
- Search Only: The case property will not be displayed in the case list or detail. However, the case list will let you search over the value of that case property (for example, a Patient ID). You can have more than one case property as search only.
- Address (Android/CloudCare): If you have GPS coordinates or an address saved as a case property, you can set the type to Address in the Case Details. This will expose a button that will call out to Google Maps and show the location pinned on the map.This only works on CommCare for Android or CloudCare.
- Distance from current location (Android/CloudCare): If you have GPS coordinates saved as a case property, this display property will show the distance between you and the case's location property in kilometers. Upon launching the case list, this display property will show the distance from your last known location until CommCare is able to acquire an accurate reading of your current location. Only supported on CommCare for Android or CloudCare.
You can change the order of properties by clicking on the vertical arrow and dragging them into your preferred order:
To remove a property click on the "x" at the end of a row.
Filtering the Case List
In some applications it is useful to filter the list of cases that can be shown. For example, you can create two separate menus that have the same case type and display different cases in each (ex. Pre-Delivery and Post-Delivery menus for a 'pregnant_mother' case type).
To add a filter click on + Add a Filter and you will be able to type an expression into the text box.
This expression can refer to any case properties and should return true if a record should be shown and false otherwise. The same functions are available as when writing Display or Validation conditions. Refer to case properties using their name (there's no need to include a "/data/" or "#case" in front of the case property). Two examples are below:
- (date(admission_date) + 7) <= today() and today() <= (date(admission_date) + 30)
- Admission date is was between 7 and 30 days ago
- if(phone_number = '', false(), (date(admission_date) + 7) <= today())
- Only show cases that have a phone number and whose admission date was more than 7 days ago
- #user/favorite_number = "1"
- Only show cases to the user if their user property "favorite_number" = 1
For more information on writing these expressions please see Common Logic and Calculations.
Sorting the Case List
The sorting section determines how cases are ordered in your case list, which is useful if you want higher priority cases to appear higher in your case list.
Your case list can have more than one column of case properties. You can sort your case list by any case property, but if you don't specify a property, it will sort by whatever is in the first column of the case list.
For example, you might want to organize your cases first by Village Name, and then by House Number. Or maybe you want to prioritize the list by Estimated Delivery Date and then Presence/absence of danger signs.
You can sort ascending/descending by four types of properties: Plain (text), Date, Integer, and Decimal. If you add a property with special formatting (i.e. ID mapping, date, etc.) it will be converted to Plain format in the sorting.
To configure sorting click on on + Add a sort property
The process is very similar to the Display Properties above:
- Sort Property - start typing the name of the property you want to sort against and the dropdown will populate with case properties that match
- Direction - ascending or descending
- Format - can be plain, date, integer, or decimal
On CommCare for Android you can also use Fuzzy Search if the property is in the sorting list and fuzzy search is turned on. This is configured on the app level, not in the case list/details section.
- You do not have to display a given case property in the case list or details in order for it to be used for sorting
- There is no limit to the number of case properties you can sort by
- If you are using a question that involves numbers you should choose the appropriate type (integer or decimal) to ensure that the case list is sorted in the way you intend
- If you do not add anything to the "sort by" section, the list will, by default, sort by the first item in the case list.
Parent Child Selection
If you have Child Cases setup for your application, you can make it easier to find a particular child case. The phone can be setup to first show a list of parent cases. After selecting a parent, the phone will then display a list of child cases for that parent. After selecting a child, you can open a particular form for that child. This can be extended to multiple levels of selection - for example selecting a village, then a woman's group and the finally a woman within that group.
On the Case List configuration for your child case menu, scroll down to the bottom of the screen. You will see an option to display a parent list first. Check the box and choose which menu will be displayed as the parent (for example, if your child case menu is displaying children, you would select the mother menu in your application).
If you would like multiple levels of selection, on the parent menu you can also setup another parent list.
Case Detail Configuration
The case detail configuration allows you to specify which case properties your users will see after having selected a case from the case list.
To add a case property click on "Add Property" and follow the directions for Display Properties (above).
You can also organize the Case Detail page using tabs. Please see documentation here.
It is also possible to use advanced text formatting to the case detail page. Formats that can be used and how to use them can be found on the text formatting page, located here.
Copying Rows from the Case List/Detail
If you want to reuse a property from the case list/detail, or from the case list/details of another screen you can use the copy case list/detail function. For example if you put a really long ID Mapping in the case list, but you also want it in the detail screen, you can now click on the ID Mapping row, Ctrl-C, navigate to the detail screen tab, click on the row below which you want to insert it, and Ctrl-V. To insert at the beginning, click on the header. User sees the built in "selected" browser indication when clicking on a row; you can hit tab to select the next row, shift+tab to select the previous. In ID Mappings in particular translations in multiple languages are maintained. You can see a demonstration here.
Calculations in the Case List/Detail
It is also possible to use calculations in the case list/details screen by enabling an add-on via the application settings screen. This feature will allow you to use custom xpath expressions to perform calculations on data and case properties that can be displayed to your mobile workers. For more information on how to enable and use this functionality, please see the following documentation.
Localization (Translations in the Case Details/List)
If your application contains multiple languages, you can define different Display Text for each language. Select the language drop down in the top-left corner of the application builder and choose the language you want to update. Update the Display Text for each property in the case list.
You can also update the translations for questions with ID mapping - this is particularly important for multiple choice questions where the choice value will only be in one language. For example, to establish Hindi translations for the choice values, change the language of the application builder to Hindi and navigate to the Case List tab for your menu. Select the property with the ID Mapping format you would like to translate, then click Edit and add Key -> Value mappings (choice value -> translation) for each of the possible choice values for that question.
Here is an example of editing the Display Text for a property
And the view of editing the ID Mapping:
If you are using ID mapping for the same question in multiple menus you can use the copy function described above.