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 https://dimagi.atlassian.net/wiki/spaces/commcarepublic/pages/2143963531.

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

1. Android Settings -> General (or similar) -> Date and Time -> Date Format (sometimes you need to uncheck "auto update date/time" first)

2. Android Settings -> General (or similar) -> Language and Input -> Locale (or "region")

3. 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

Open

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

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).

Open

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.