Bootstrap Date & Time picker

by Gisle Hannemyr

This chapter ...

Table of contents

Drupal projects discussed in this chapter: Bootstrap, Bootstrap Date & Time Picker, Moment.js.

Introduction

This chapter describes how to install and use the Bootstrap Date & Time picker (BDTP) on a Drupal 7 website.

Please note that this can only be used on sites set up with a subtheme of the Bootstrap theme. In addition to the Bootstrap theme, it relies on two bridge modules.

redflagThere are a lot versions of the Bootstrap Datepicker library around, so googling for help may lead to information about some other version. The official documentation is here.

[TBA]

Installation

Before starting, bake sure the Boostrap installed, enabled and set as default. Refer to this chapter to learn how to install Boostrap. Also make sure jQuery update is enabled.

To install the module first download the projects bdtpicker depends on and install them below the modules directory on the site. You may do this with drush. Navigate to or below the webroot and use the following commands:

$ [drush dl date -y] clone from g61.no util patch is in Drupal repo
$ drush dl libraries -y
$ drush dl moment -y

This downloads the the required date and libraries projects, and the Drupal 7 bridge module for the Moment.js library. It does not install the libraries.

To clone the required libraries, and to checkout stable versions compatible with the bridge modules, you can use these commands:

$ cd html/sites/all/libraries
$ git clone https://github.com/Eonasdan/bootstrap-datetimepicker.git
$ git clone https://github.com/moment/moment.git
$ git clone https://github.com/moment/moment-timezone.git
$ cd bootstrap-datetimepicker
$ git checkout 3.1.4
$ cd ../moment
$ git checkout master
$ cd ../moment-timezone
$ git checkout master

To save you typing this in, you may put these commands in dllibs.sh in the siteroot (i.e. above the webroot).

To update a library cloned with git to the latest version, navigate to the library's top directory and use the following pair of commands.

$ git remote update
$ git pull

Post installation

It is recommended to use ver. 4 of the library.

In order to do this, clone the Bootstrap Date & Time Picker repo (snapshot version 2017-05-06).

$ git clone --branch 7.x-3.x https://git.drupal.org/project/bdtpicker.git

Then I switched to branch “localv4”, and applied the patch bdtpicker-v4_compatibility-2538366-7.patch to make it compatible with ver. 4 of the library. 

$ git checkout -b localv4
$ git apply bdtpicker-v4_compatibility-2538366-7.patch
$ git add .
$ git commit -am 'Issue #2538366 by madt: Compatibility with bdtpicker V4' \
  --author="madt <madt@283586.no-reply.drupal.org>"

The patch applied cleanly, and the patched version exists in the local git repo, dated 2018-08-04.

To use the patched version, switch to the lates version of the library's master branch.

$ cd sites/all/libraries/bootstrap-datetimepicker
$ git tag
…
$ git checkout master

Now you should be ready to enable the module:

$ drush en bdtpicker -y

Then navigate to Reports » Status report, and check that all required libraries are found.

Setting up and testing

Set the Drupal date formats and first day of the week before you start using the module.

The module only has a single setting. To see and alter it, navigate to Configuration » User interface » Bootstrap Date & Time picker settings. You can unset or set this flag: “Attach Bootstrap Date & Time picker to Authored on field on Content create/update form”. If this is set, BDTP will be used for the “Authored on” field in the form for creating new content. If this is not set, the standard text field for entering dates will be used. Even if you are not going to use the BDTP for this field, it provides an out-of-the-box opportunity to test that the BDTP is working as intended before proceeding.

bdtp01.png
Example of BDTP used for the “Authored on” field.

The screen shot above shows how the BDTP should look like when BDTP is used for the “Authored on” field.

redflagTo use this test, make sure the administration theme is not enabled when testing. I.e. under Appearance, uncheck the “Use the administration theme when editing or creating content” checkbox in the “Administration theme” panel.

The screenshot above is taken from a clean install of Drupal 7 with Boostrap. The project was patched as described above to use version 4 of the Bootstrap Date & Time picker library. The versions of libraries can be inspected in the “Status” report. The most recent releases at the time of writing (March 2020) where:

Locale

The Bootstrap 3 Datepicker library has its own translation into a number of languages, including “Norsk Bokmål”. Setting this in Drupal (Configuration » Regional and language » Languages), gives Norwegian names for months and days, and sets Monday as the first day of the week.

Using the GUI

When you add a date field using the GUI, you must select the “Text field” widget type to get the calendar pop-up. The “Select list” widget type provides a the pull down menu of date fields from the Date module.

redflagThe BDTP is overloading the “Text field” widget to to provide the popup picker. This is not very intuitive, but there is a reason for it: Implementation as widget type.

Known bugs

Expanding “More settings and values” let you set “Default values”. Setting a relative “Default end date” does not work, and triggers this warning:

Warning: DateTime::format(): The DateTime object has not been correctly initialized by its constructor in DateObject->format() …

Using the form contructor

Documentation:

The Drupal bdtpicker module provides a datepicker popup to Drupal. It is designed to work together with Date Fields, but also works with plain date_text form elements.

Minimal example:

function rbg_bdtpicker_demo_form($form, &$form_state) {
  $form['my_date'] = array(
    '#type' => 'date_text',
    '#title' => t('My date'),
    '#bdtpicker' => TRUE,
  );
  $form['actions'] = array(
    '#type' => 'actions',
    'submit' => array(
      '#type' => 'submit',
      '#value' => t('Save'),
    ),
  );

  return $form;
}

Activates data picker and produces:

$form_state['values'] = array(
    [my_date] => 2017-08-01 17:12
    …
);

Options:

  $form['my_popup'] = array(
    '#date_increment' => 10, // stepping (60 will disable minutes)
    '#date_format' => 'Y-m-d H:i', // date format to use
  );

The function bdtpicker_element_date_text_process() copies everything in the form constructor prefixed with "#datepicker_" into another form array that is made available to the library. So if you wrap Bootstrap 3 Datepicker options in #datepicker_options", they are picked up and used.

For example, to change the initial viewMode form "days" to "years", you can use the following in the form constructor:

  $form['my_popup'] = array(
    '#type' => 'date_text',
    '#title' => t('My popup'),
    '#bdtpicker' => TRUE,
    '#datepicker_options' => array(
      'viewMode' => 'years',
    ),
  );

Final word

TBA

Last update: 2020-03-18