Calendar | Commerce Frontend Development

Edit in GitHub Log an issue

The Calendar widget is a customized jQuery Datepicker Widget that enables selecting a data using a pop-up or an in-line calendar. Calendar is also responsible for:

Merging the global configuration with the options that are passed from PHP when Calendar is initialized.
Taking into account server time zone offset.
Converting date and time formats to avoid inconsistency in Zend Date format and Datepicker format.
Making the calendar initialization easier.
The Calendar widget source is lib/web/mage/calendar.js.

Initialize

For information about how to initialize a widget in a JS component or .phtml template, see the Initialize JavaScript topic.

Configure

The calendar widget's global configuration is a set of default options that are applied when each calendar instance is initialized. It includes the following:

Translations for days, months, and control buttons
Date and time format
Animation settings
Calendar pop-up mode
Server time zone offset

Global configuration for calendar is stored in a jQuery object as a hash of properties. Having global configuration set enables specifying all translations and default options at once, and use it for all instances of calendar, and it enables usage of inline translation for the calendar. During initialization, the calendar widget merges the hash of options from the global configuration, and the options which are transferred from PHP, and then passes the merged options to datepicker.

Example of setting global widget configuration follows:

require([
  'jquery',
  'mage/calendar'
  ], function ( $ ) {
    $.extend(true, $, {
      calendarConfig: { ... }
    });
});
Copied to your clipboard
require([
  'jquery',
  'mage/calendar'
  ], function ( $ ) {
    $.extend(true, $, {
      calendarConfig: { ... }
    });
});

Validate

To validate the calendar widget, specify the required dateFormat parameter:

'validate-date': [
    function (value, params, additionalParams) {
        var test = moment(value, utils.convertToMomentFormat(additionalParams.dateFormat));

        return $.mage.isEmptyNoTrim(value) || test.isValid();
    },
    $.mage.__('Please enter a valid date.')
];
Copied to your clipboard
'validate-date': [
    function (value, params, additionalParams) {
        var test = moment(value, utils.convertToMomentFormat(additionalParams.dateFormat));

        return $.mage.isEmptyNoTrim(value) || test.isValid();
    },
    $.mage.__('Please enter a valid date.')
];

This example shows how to add date validation for a calendar widget:

data-validate="{'required-entry': true, 'validate-date': {dateFormat: 'MM/dd/Y'}}"
Copied to your clipboard
data-validate="{'required-entry': true, 'validate-date': {dateFormat: 'MM/dd/Y'}}"

Options, methods, and events

Most options, methods, and events for the calendar widget correspond to the jQuery Datepicker Widget options.

Code sample

This example shows how to initialize the calendar widget, including custom parameters.

<div class="field">
    <label>Date : </label>
    <input type="text" class="input-text" id="example-date" style="width: auto" name="example-date" />
</div>

<script>
  require([
    'jquery',
    'mage/translate',
    'mage/calendar'
    ], function ($, $t) {
      $('#example-date').calendar({
        changeMonth: true,
        changeYear: true,
        showButtonPanel: true,
        currentText: $t('Go Today'),
        closeText: $t('Close'),
        showWeek: true
      });
    })
</script>
Copied to your clipboard
<div class="field">
    <label>Date : </label>
    <input type="text" class="input-text" id="example-date" style="width: auto" name="example-date" />
</div>

<script>
  require([
    'jquery',
    'mage/translate',
    'mage/calendar'
    ], function ($, $t) {
      $('#example-date').calendar({
        changeMonth: true,
        changeYear: true,
        showButtonPanel: true,
        currentText: $t('Go Today'),
        closeText: $t('Close'),
        showWeek: true
      });
    })
</script>