Dates & Times

Overview

Over the course of HQ's history, we have trialed and tested several date and time pickers. We have finally settled on one library, Tempus Dominus, for its accessibility features and ease of localization. Below are examples of how to use it in various scenarios, as well as guidance for how to replace older tools on Bootstrap 3 pages with this new library.

Tempus Dominus emerged from the eonasdan-bootstrap-datetimepicker, which is still referenced in Bootstrap 3 pages as the datetimepicker jQuery plugin. Any references to datetimepicker should be replaced with tempusDominus when migrating a page from Bootstrap 3 to 5.

There are also references to the jQuery UI datepicker plugin, the timepicker plugin (from the abandoned bootstrap-timepicker project), and daterangepicker (from bootstrap-daterangepicker) in Bootstrap 3 pages. All of these should be replaced with Tempus Dominus during the migration of a page from Bootstrap 3 to 5.

Simple Date Picker Widget

If you are in need of a simple date picker widget that returns a format in YYYY-MM-DD, then your best option is to add the date-picker CSS class to any text input and make sure that hqwebapp/js/bootstrap5/widgets is included as part of your javascript dependencies. Additionally, you will want to use the @use_tempusdominus decorator on the view using the widget to ensure the CSS is loaded to the page properly.

The hqwebapp/js/bootstrap5/widgets module when loaded to a page will look for input fields with the date-picker CSS class, and apply the Tempus Dominus plugin to that field.

<input class="date-picker form-control"  type="text" name="a_date" />

Advanced Date Picker

If you are interested in having a date-only picker widget with extra options, you can use Tempus Dominus without the clock component. See the project's documentation for additional guidance.

<input id="js-dateonly" class="form-control" type="text" name="dateonly" />

import { TempusDominus } from '@eonasdan/tempus-dominus';

new TempusDominus(
    document.getElementById('js-dateonly'),
    {
        display: {
            theme: 'light',
            components: {
                clock: false,
            },
        },
        localization: {
            format: 'L',
        },
    },
);

Date & Time

If you want to choose a date and time together, the default state of the Tempus Dominus plugin is a good starting point. See the project's documentation for additional guidance.

<input id="js-id-date-end" class="form-control" type="text" name="date_end" />

import { TempusDominus } from '@eonasdan/tempus-dominus';

new TempusDominus(
    document.getElementById('js-id-date-end'),
    {
        display: {
            theme: 'light',
        },
    },
);

Time Only

If you only need to choose a time, you can use Tempus Dominus without the calendar option. See the project's documentation for additional guidance.

<input id="js-id-timepicker" class="form-control" type="text" name="timepick" />

import { TempusDominus } from '@eonasdan/tempus-dominus';

new TempusDominus(
    document.getElementById('js-id-timepicker'),
    {
        display: {
            theme: 'light',
            components: {
                calendar: false,
            },
        },
        localization: {
            format: 'LT',
        },
    },
);

If you want a time-picker in 24-hour format, the example below provides a good starting point.

<input id="js-id-timepicker-24" class="form-control" type="text" name="timepick24" />

import { TempusDominus } from '@eonasdan/tempus-dominus';

new TempusDominus(
    document.getElementById('js-id-timepicker-24'),
    {
        display: {
            theme: 'light',
            components: {
                calendar: false,
            },
        },
        localization: {
            hourCycle: 'h23',
            format: 'H:mm',
        },
    },
);

Date Range

If you need to select a range between two dates (start and end), you can use Tempus Dominus with the dateRange option enabled. Previously, we used bootstrap-daterangepicker as the plugin of choice. The example below provides a drop-in replacement for the default usage of bootstrap-daterangepicker if you come across it in older Bootstrap 3 pages. For additional guidance, see the documentation for Tempus Dominus.

<input id="js-date-range" class="form-control" type="text" name="date_range" />

import { TempusDominus } from '@eonasdan/tempus-dominus';

new TempusDominus(
    document.getElementById('js-date-range'),
    {
        dateRange: true,
        multipleDatesSeparator: " - ",
        display: {
            theme: 'light',
            components: {
                clock: false,
            },
        },
        localization: {
            format: 'L',
        },
    },
);