Bug 28376

Summary: Flatpickr introduction for datetime picker
Product: Koha Reporter: Tomás Cohen Arazi <tomascohen>
Component: TemplatesAssignee: Owen Leonard <oleonard>
Status: CLOSED FIXED QA Contact: Tomás Cohen Arazi <tomascohen>
Severity: enhancement    
Priority: P5 - low CC: bolshawh, david, dcook, gmcharlt, jonathan.druart, kyle, martin.renvoize, tomascohen
Version: master   
Hardware: All   
OS: All   
See Also: https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=28351
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=29222
https://bugs.koha-community.org/bugzilla3/show_bug.cgi?id=33886
Change sponsored?: --- Patch complexity: Small patch
Documentation contact: Documentation submission:
Text to go in the release notes:
This patch begins the process of replacing an obsolete jQuery plugin with a new library for selecting dates and times. Koha uses the jQueryUI "datepicker" widget for selecting dates, and uses an additional plugin, "jQuery Timepicker Addon," when adding time selection to the widget. This additional plugin has not been updated for many years. The new library, Flatpickr, will eventually replace both the jQuery Timepicker Addon and the jQueryUI datepicker widget. This replacement process begins here with the new Flatpickr calendar widget being added to Circulation -> Renew, Reports -> Patron statistics wizard, and Administration -> Patron categories.
Version(s) released in:
21.11.00
Bug Depends on:    
Bug Blocks: 28928, 28978, 29239, 29837    
Attachments: Bug 28367: PROOF OF CONCEPT Replace jQueryUI date/timepicker with Flatpickr
Bug 28367: PROOF OF CONCEPT Replace jQueryUI date/timepicker with Flatpickr
Bug 28376: Replace jQueryUI date/timepicker with Flatpickr
Bug 28376: Replace jQueryUI date/timepicker with Flatpickr
Bug 28376: Replace jQueryUI date/timepicker with Flatpickr
Bug 28928: Minor follow-ups to Bug 28376 - Flatpickr introduction
Bug 28376: (follow-up) Replace jQueryUI date/timepicker with Flatpickr

Description Tomás Cohen Arazi 2021-05-18 16:46:37 UTC
The latest jquery-ui-timepicker-addon version dates back to 2016, and we are using one dated 2014.

We should replace it with something that's maintained. 'flatpickr' [1] could be used to replace timepickers and also datepickers.

It is flexible enough for us to customize things, including date formatting and translations.

[1] https://flatpickr.js.org/
Comment 1 Owen Leonard 2021-05-20 17:27:42 UTC Comment hidden (obsolete)
Comment 2 Tomás Cohen Arazi 2021-06-02 14:49:47 UTC
I really like it.

The code is really simple, and handling dateformat seems sleek as well.

The only thing I could mention is the modal feels too big.
Comment 3 Jonathan Druart 2021-07-19 14:14:32 UTC
Yes, go for it!

Can we have a working version of the patch?

I would like, as a first step, a POC witch takes care of two occurrences, a simple one and a complex one.

We need to think about the edge cases:
* time format (now it's 12h when the syspref is 24h)
* manual editing
* format validation
* range validation (from/to)
* "from today only" (no date from the paste)
Comment 4 Jonathan Druart 2021-07-19 14:15:49 UTC
(In reply to Jonathan Druart from comment #3)
> * time format (now it's 12h when the syspref is 24h)

Well, maybe not, but it's confusing!
https://snipboard.io/IzOBMF.jpg
Comment 5 Jonathan Druart 2021-07-19 14:19:02 UTC
There is also bootstrap-datepicker - https://github.com/uxsolutions/bootstrap-datepicker
Comment 6 Tomás Cohen Arazi 2021-07-20 19:59:59 UTC
(In reply to Jonathan Druart from comment #5)
> There is also bootstrap-datepicker -
> https://github.com/uxsolutions/bootstrap-datepicker

I like the bootstrap integration. FTR: I chose Flatpickr because it looked like a more active project (maybe I'm biased and it is just that is buggier :-P) but also because it had time handling.
Comment 7 Owen Leonard 2021-07-21 14:13:37 UTC Comment hidden (obsolete)
Comment 8 Owen Leonard 2021-07-21 14:15:50 UTC
The only thing I've found so far that Flatpickr lacks compared to jQueryUI is an option to show a "Today" button in the calendar widget. There is an addon which can provide this (https://github.com/jcsmorais/shortcut-buttons-flatpickr) but I'm not sure it's worth adding another dependency.

FWIW you can type the word "today" in a Flatpickr date field and it will correctly interpret it.
Comment 9 Owen Leonard 2021-07-30 13:15:32 UTC Comment hidden (obsolete)
Comment 10 David Nind 2021-07-31 18:45:51 UTC
Created attachment 123352 [details] [review]
Bug 28376: Replace jQueryUI date/timepicker with Flatpickr

This patch is a proof of concept demonstrating how jQueryUI date & time
pickers could be replaced using the Flatpickr library
(https://flatpickr.js.org/).

NEW: I've modified the default configuration of Flatpickr instances so
that a "Clear date" link is automatically appended. This eliminates the
need to add a button to the markup and event handling for each case.

NEW: Date/time formatting should be corrected in this revised patch.

The patch modifies three pages as test cases:
 - Circulation -> Renew (with SpecifyDueDates enabled), to demonstrate
   date and time selection.
   - NEW: You can also test the datepicker shown when you renew an
     on-hold item. This demonstrates a configuration which requires that
     the selection be after today.
 - Administration -> Patron categories -> New category, to demonstrate a
   calendar-only date picker enforcing a date after today.
 - NEW: Reports -> Patrons. The "Date of birth" fields are linked so
   that the second cannot be before the first.

I've made some customizations to the default Flatpickr library's CSS and
incorporated it into staff-global.scss, so you must rebuild the staff
client SCSS
(https://wiki.koha-community.org/wiki/Working_with_SCSS_in_the_OPAC_and_staff_client).

Signed-off-by: David Nind <david@davidnind.com>
Comment 11 David Nind 2021-07-31 18:47:34 UTC
Everything seemed to work okay for me. Also like that the calendar icon is now back inside the input box.
Comment 12 Tomás Cohen Arazi 2021-08-20 12:22:50 UTC
Created attachment 123997 [details] [review]
Bug 28376: Replace jQueryUI date/timepicker with Flatpickr

This patch is a proof of concept demonstrating how jQueryUI date & time
pickers could be replaced using the Flatpickr library
(https://flatpickr.js.org/).

NEW: I've modified the default configuration of Flatpickr instances so
that a "Clear date" link is automatically appended. This eliminates the
need to add a button to the markup and event handling for each case.

NEW: Date/time formatting should be corrected in this revised patch.

The patch modifies three pages as test cases:
 - Circulation -> Renew (with SpecifyDueDates enabled), to demonstrate
   date and time selection.
   - NEW: You can also test the datepicker shown when you renew an
     on-hold item. This demonstrates a configuration which requires that
     the selection be after today.
 - Administration -> Patron categories -> New category, to demonstrate a
   calendar-only date picker enforcing a date after today.
 - NEW: Reports -> Patrons. The "Date of birth" fields are linked so
   that the second cannot be before the first.

I've made some customizations to the default Flatpickr library's CSS and
incorporated it into staff-global.scss, so you must rebuild the staff
client SCSS
(https://wiki.koha-community.org/wiki/Working_with_SCSS_in_the_OPAC_and_staff_client).

Signed-off-by: David Nind <david@davidnind.com>
Signed-off-by: Tomas Cohen Arazi <tomascohen@theke.io>
Comment 13 Tomás Cohen Arazi 2021-08-20 12:25:22 UTC
I like the aesthetics of this library and it works like a charm. It is an easy replacement to the current library.

The use cases work: limiting date ranges, time pick, etc.

The only thing I would change is the font size, as it feels a bit bigger than the rest of the Koha fonts. We might even revisit the font itself.
Comment 14 Jonathan Druart 2021-08-30 14:14:59 UTC
What's the next step? This should not be part of 21.11 alone, we must replace all other occurrences.
Comment 15 Jonathan Druart 2021-08-30 14:27:36 UTC
We should be able to set a date without using the widget (ie. keep date validation and remove readonly on the input).
Comment 16 Jonathan Druart 2021-08-30 15:32:28 UTC
(In reply to Jonathan Druart from comment #15)
> We should be able to set a date without using the widget (ie. keep date
> validation and remove readonly on the input).

From IRC
 oleonard> Joubu: flatpickr's "allowInput" option is true by default.

Tried again and it's working as expected now (??)
Comment 17 Jonathan Druart 2021-08-30 16:08:57 UTC
Pushed to master for 21.11, thanks to everybody involved!
Comment 18 Jonathan Druart 2021-09-01 13:45:31 UTC
Created attachment 124368 [details] [review]
Bug 28928: Minor follow-ups to Bug 28376 - Flatpickr introduction

This patch corrects three errors in the original Flatpickr introduction
patch:

- Missing document.ready() in borrowers_stats.tt.
- Redundant calendarFirstDayOfWeek setting in caregories.js
- Missing preventDefault() in calendar.inc

The first two issues don't appear to cause any malfunction but are best
practices. The third issue can cause the page to scroll unexpectedly.

To reproduce this bug, go to (for instance) Administration -> Patron
categories -> New category.

 - If necessary, narrow the height of your browser window so that there
   is a vertical scrollbar.
 - Scroll down the page so that the "Until date" field is at the top.
 - Click the "X" next to the field.
 - The page will scroll to the top.

Apply the patch and test again. The page jump should not occur.

Signed-off-by: Jonathan Druart <jonathan.druart@bugs.koha-community.org>
Comment 19 Jonathan Druart 2021-11-15 10:02:32 UTC
Created attachment 127627 [details] [review]
Bug 28376: (follow-up) Replace jQueryUI date/timepicker with Flatpickr

Remove uneeded include of flatpickr.min.js (we load it from
calendar.inc)
Comment 20 Jonathan Druart 2021-11-15 11:42:12 UTC
(In reply to Jonathan Druart from comment #19)
> Created attachment 127627 [details] [review] [review]
> Bug 28376: (follow-up) Replace jQueryUI date/timepicker with Flatpickr
> 
> Remove uneeded include of flatpickr.min.js (we load it from
> calendar.inc)

Pushed to master.