Add xPath function for easily adding years, months, days, etc to date value

[jkuester]

Currently there is not an easy way in an ODK form to add/subtract a specific number of years/months/days/ etc from a date value in a calculation. Often I have seen decimal-date-time + date functions used to adjust a date value by a set number of days (convert the date to a number of days since epoch, then use arithmetic to adjust the day count, then convert the days back into a date value). However, this process is inconvenient and is particularly difficult when trying to adjust a date with a dynamic offset.

It would be very useful to have a custom xPath function that forms could use to perform this operation.

I am not sure about the naming yet, but I am thinking we could either add one function:

shift-date(date, years, months, days, hours, minutes)
// Or
offset-date(date, years, months, days, hours, minutes)

Or multiple separate functions:

add-years(date, years), 
add-months(date, years), 
add-days(date, years)

[garethbowen]

The problem with shift and offset is it's not clear which direction the date is being moved. So add makes more sense to me. That does mean though that in the use case we're working with everyone will have to <input> * -1 to do the subtraction but I think that's ok.

I like having just one function which takes all the different date units, so app builders can do the maths on multiple input fields with a single function, and we can test combinations thoroughly.

I think I'd go with:

add-date(date, years, months, days, hours, minutes);

We could also add a subtract-date if you think that's helpful.

[jkuester]

@garethbowen I recently found this issue: https://github.com/medic/cht-core/issues/5468 which seems to pretty much cover what we are discussing here (and more).

We seem to be pretty in line with the goals of that other issue, but I wanted to check with you and make sure we still wanted to move forwards with the add-date function (got the PR ready: https://github.com/medic/cht-core/pull/7729) or if there was anything we needed to rethink, given the context of 5468...

[garethbowen]

@jkuester Nice spotting. Yes I think this is consistent with that issue, specifically option 3 in this comment. So I think we go for it, and then after 4.0.0 perhaps the Allies team can follow up with App Developers about what other common functions we could include.

[jkuester]

This is ready for AT on 7694-add-date-function.

The best way to test this functionality is to just deploy the default config and then verify that a person's birth date can be set properly (when using the month/year values instead of the calendar picker) with the following default forms:

• person-create
• person-edit
• health_center-create
• district_hospital-create
• clinic-create

Those forms have all been updated to use the new add-date function to calculate the birth date from the month/year values.

[tatilepizs]

Config: Default Environment: Local with docker helper script Platform: WebApp Browser: Chrome cht-core version: 7694-add-date-function

district_hospital-create

health_center-create

clinic-create

person-create

person-edit