Dates
Date Display and Formatting
There are three common scenarios for manipulating the display or formatting of Dates in a CommCare application, each with a different method of influencing the system.
To understand your collected date data, please visit Understanding Times and Dates
Changing the format for how dates are displayed in labels or other read-only text
Example
A Label question which displays a date collected elsewhere, like
"The mother's estimated date of delivery is 07-07-2019"
How to Update
You can use the format-date() function when building a date reference to change the formatting, including text or limiting which elements are displayed.
Changing the format of date collection
Example
A date question currently collects date input from the user in "MM-DD-YYYY" format on an Android device, and the user wishes to collected the dates as "DD-MM-YYYY"
How to Update
CommCare collects date data according to the current Android Phone Settings for an individual device. A device purchased in the USA would show a date question as "07-20-1990" while a device purchased in the UK would show a date question as "20-07-1990". Both questions would submit the same data to the server, regardless of how data was collected.
The method for changing this format differs by device manufacturer, but the top 3 common ways to change it are as follows
Android Settings -> General (or similar) -> Date and Time -> Date Format (sometimes you need to uncheck "auto update date/time" first)
Android Settings -> General (or similar) -> Language and Input -> Locale (or "region")
Android Settings -> General (or similar) -> Language and Input -> Language (when no locale or region is listed in this menu) -> Choose the language for device (English, Spanish, French, etc) -> Choose the Region for the device (IE: Guatemala)
In the latter two options, many devices treat the date format as part of the "region" that the phone is currently configured for. On these devices the date format can only be changed by changing the region to match the appropriate one.
Changing the calendar used to a "non-gregorian" calendar
Example
An app wants to collect or display dates according to the Ethiopian calendar.
See below
Calendars
Use of the Alternate Calendar Systems in CommCare Android
CommCare's Android client supports hooks for manipulating dates in select calendar systems other than Gregorian (i.e. Nepali and Ethiopian).
Dates are always stored inside of the form as ISO8601 compliant Gregorian dates, so exports and incoming data will need to handle data in that format.
During form entry dates can be both collected and displayed in alternate calendars using two mechanisms. In each system a key is provided from the following table to request that specific calendar
Calendar Key | Description |
---|---|
ethiopian | Ethiopian Calendar (Supports Amharic fonts if the phone's locale is set appropriately) |
nepali | Nepali Calendar (CommCare Android 2.19+) |
Collecting a date using the date question type
Setting a date question's appearance attribute to one of the supported keys will result in date entry being performed using that calendar. Note again that the date stored in the form is a standard Gregorian date, so any calculations you will do will be in that format and exports will contain a standard Gregorian date.
In CommCareHQ you can accomplish this by setting the key in the Advanced -> Appearance Attribute field for the date question (see below).
Displaying a Date in an Alternative Format
When dates are displayed in a form, the date can be passed to the format-date-for-calendar() function to return a string which prints the date in the appropriate calendar. The first argument to the function should be a standard date, and the second should be the key of that calendar, passed as a string.