Dates and periods in a multi-calendar environment

[HendrikThePendric]

Context

On Wednesday, June 12th 2019 a meeting took place to discuss how we are currently working with dates and periods in DHIS2 and ways to improve this. The main reason for organising the meeting was the fact that the current implementation in the front-end is fragmented and incomplete.

Several people were present:

• @jenniferarnesen
• @abyot
• @edoardo
• @HendrikThePendric

Current situation

• Dates and periods are generated both in the frontend and the backend
• In the frontend we are doing period generation in multiple places
• Quite a lot of apps require period selection, such as:
  • Data-entry
  • Tracker
  • Reports
  • Maintenance
  • Analytics
• Even more apps require a date picker
• Some new (external) apps, such as the scorecard and bottleneck analysis apps will also require period selection
• The DHIS 2 platform is supposed to support multiple calendars, but none of the React apps actually support non-gregorian calendars. On the other hand, the dhis2-core backend and a jQuery solution do support multiple calendars.

Problem analysis

• The fact that periods are generated in multiple places in our front-end ecosystem is bad. We need to consolidate this into a single location
• Even after consolidation, if we keep generating periods in the front-end and back-end, we would have to maintain calendar implementations for several calendar types in both places and make sure they are producing identical results.
• The need for offline-support has high priority. However, this is not relevant to all apps. And even for apps that do require offline support, it is safe to assume they will be connected to the internet periodically, so caching responses from the webapi in the browser could be a viable strategy.
• The apps that need offline support are likely to require fairly narrow range of periods, so this makes the caching strategy even more viable.

Proposed approach

• Fully rely on the server implementation, so we don’t have to maintain identical solutions in Java and JavaScript
• Expose webapi endpoints to fetch period related lists, i.e.:
  • Get months for a given year
  • Get biWeeks for a given year
  • Get get days for a given year and month
  • Etc
• Expose a webapi endpoint to get relative period types
• Include localised displayNames in these api-responses
• Build async date-picker and period-selection ui-widgets, i.e.:
  • DatePicker
  • PeriodMultiSelect
  • PeriodSingleSelect
• Incorporate these components into existing React apps
• For apps that need offline support, add a caching mechanism using localStorage/IndexedDB. So far we have identified data-entry and tracker-app that would require this.
• Older apps (e.g., Pivot table, Event reports) can keep using the jQuery solution, because it has been proven to work adequately and eventually they will be phased out, so consolidation is not as relevant.

[HendrikThePendric]

@larshelge Could you please give your opinion about the proposed approach? Do you see this as a way forward, or do you think we should have a fully client-side implementation of several calendars too?

[varl]

Related: https://github.com/dhis2/d2-ui/pull/428

[abyot]

I had a meeting with @larshelge last week. He is more inclined to have a common JS library and we agreed to tackle this from two angles:

1. period library without a datepicker component in it and
2. datepicker component

I will be looking into 1 - pure period library. For this I am wondering if we can build on Int.DateTimeFormat ?

Latest browser's are coming with Internationalization API support and we should be able to capitalize on that. Do we have list of browser versions that we support and do not support?

[ismay]

@abyot I was wondering if there are any existing solutions out there that we can leverage, or build on for 1. Do you know of any? I can imagine it'd be nice to contribute to something existing if possible.

[abyot]

@ismay not really much. I am thinking of building on Int.DateTimeFormat and probably Luxon for manipulating date and times which we need for generating periods.

[HendrikThePendric]

@abyot so, just to confirm: we'll need to build these components with full support for all calendar systems, including Nepalese, etc?

[abyot]

yes, will have to support all the calendars out there.

I know Int.DateTimeFormat does not have support to Nepalese. I don't know may be because Nepalese calendar works with a mapping table than a generic algorithm? ... still better to build on native browser and probably fill the missing ones ourselves.

[HendrikThePendric]

still better to build on native browser and probably fill the missing ones ourselves.

Yeah quite likely. It's something I'd really have to dive into a bit to make any suggestions.

I did a tiny little bit of research into this and while I couldn't find any Date pickers, or date utility libs, with direct support for Nepalese, I did find some converters for various calendars incl. Nepalese. Perhaps we could utilise base our solution around Int.DateTimeFormat + one of these converters....