zebra_datepicker

v2.2.0

Published

2 months ago

A super-lightweight, highly configurable, cross-browser date / time picker jQuery plugin

Downloads

2,108

0High
0Medium
0Low

stefangabos

jquery-plugin ecosystem:jquery calendar date datepicker form iso-8601 ui

Zebra Datepicker

A super-lightweight, highly configurable, cross-browser date time picker jQuery plugin

Enhance your forms with the powerful and highly-configurable Zebra Datepicker date time picker jQuery plugin. This date time picker adds an intuitive calendar interface for selecting dates and times, complete with a convenient month and year jump feature. The selected date will be formatted and entered into the input field according to your specified options. Simply attach the plugin to your input fields and let the calendar icon do the rest.

Features

it is small – it weighs around 30KB minified (9.1KB gzipped) offering the best ratio of features per used bytes
it is both a date picker as well as a time picker
it's cross-browser – works in every major browser; works also in Internet Explorer 6 (as long as you are using a version of the date picker that is less than 2.0.0)!
has a default color scheme that blends-in well with almost any design, and it's easily customizable through the well-organized CSS file; two additional themes are included, one of them being for use with Twitter Bootstrap
offers an intuitive interface allowing for easy navigation through months and years
offers an intuitive mechanism for disabling dates and date ranges using a syntax similar to cron's syntax
supports defining of custom weekend days for countries that don't have the weekend on Saturday and Sunday
supports most of date formats you can think of, borrowing the syntax of PHP's date function
supports all sorts of combinations for starting and ending dates
date pickers can be "paired" – where one or more date pickers will use the value of another date picker as starting date
supports internationalization
supports RTL languages
works by automatically attaching a small calendar icon to the indicated input fields which displays the attached date picker when clicked.
it's compatible with AMD and CommonJS

🎂 Support the development of this project

Your support is greatly appreciated and it keeps me motivated continue working on open source projects. If you enjoy this project please star it by clicking on the star button at the top of the page. If you're feeling generous, you can also buy me a coffee through PayPal or become a sponsor. Thank you for your support! 🎉

Demo

See the demos

Requirements

Zebra Datepicker has no dependencies other than jQuery 1.7.0+ and requires that the page you are using the plugin on to have a strict doctype like:

<!doctype html>

Installation

Zebra Datepicker is available as a npm package. To install it use:

# the "--save" argument adds the plugin as a dependency in packages.json
npm install zebra_datepicker --save

How to use

First, load jQuery from a CDN and provide a fallback to a local source like:

<script src="https://code.jquery.com/jquery-3.5.0.min.js"></script>
<script>window.jQuery || document.write('<script src="path/to/jquery-3.5.0.js"><\/script>')</script>

Load the Zebra Datepicker jQuery plugin:

<script src="path/to/zebra_datepicker.min.js"></script>

Alternatively, you can load Zebra Datepicker from JSDelivr CDN like this:

<!-- for the most recent version, not recommended in production -->
<script
  src="https://cdn.jsdelivr.net/npm/zebra_datepicker@latest/dist/zebra_datepicker.min.js"></script>

<!-- for a specific version -->
<script
  src="https://cdn.jsdelivr.net/npm/[email protected]/dist/zebra_datepicker.min.js"></script>

<!-- replacing "min" with "src" will serve you the non-compressed version -->

Load the style sheet file from a local source

<link rel="stylesheet" href="path/to/theme/zebra_datepicker.min.css">

...or from JSDelivr CDN

<!-- for the most recent version of the "default" theme -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/zebra_datepicker@latest/dist/css/default/zebra_datepicker.min.css">

<!-- for the most recent version of the "bootstrap" theme -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/zebra_datepicker@latest/dist/css/bootstrap/zebra_datepicker.min.css">

<!-- replacing "min" with "src" will serve you the non-compressed version -->

Zebra Datepicker is also available on cdnjs, one of the most famous free and public web front-end CDN services

Now, within the DOM-ready event, attach the Zebra Datepicker plugin to a <input type="text"> control.

$(document).ready(function() {

    // assuming the controls you want to attach the plugin to
    // have the "datepicker" class set
    $('input.datepicker').Zebra_DatePicker();

});

This will attach a calendar and to the specified element(s). Clicking the icon, will make the date picker visible.

To get a reference to the instance of Zebra DatePicker attached to an element do:

var datepicker = $('selector').data('Zebra_DatePicker');

Configuration options

Properties

All parameters are optional.

Note that any of the properties below may also be set via data attributes. To do this you have prefix the name of the property you want to set with data-zdp_. One important thing to remember is that if the value of the property is an array you’ll have to use double quotes inside the square brackets and therefore single quotes around the attribute. See example.

Events

`onChange`

Callback to be executed whenever the user changes the view (days/months/years/time), as well as when the user navigates by clicking on the next/previous icons in any of the views;

The callback function receives 2 arguments

the current view (days, months, years or time)
an array containing the active elements (not disabled) from the view, as jQuery elements, allowing for easy customization and interaction with particular cells in the date picker's view

The this keyword inside the callback function refers to the element the date picker is attached to, as a jQuery object. To get the plugin's properties do properties = this.data('Zebra_DatePicker').

For simplifying searching for particular dates, each element gets a date data attribute whose format depends on the value of the view argument as follows:

YYYY-MM-DD for elements in the days view
YYYY-MM for elements in the months view
YYYY for elements in the years view

Note that this data attribute is not also set for elements in the time view.

Here's how we could highlight the 24th day of each month of each year:

$('selector').Zebra_DatePicker({

    //  execute a function whenever the user changes the view
    //  (days/months/years), as well as when the user
    //  navigates by clicking on the "next"/"previous" icons
    //  in any of the views
    onChange: function(view, elements) {

        //  on the "days" view...
        if (view === 'days') {

            //  iterate through the active elements in the view
            elements.each(function() {

                //  to simplify searching for particular dates,
                //  each element gets a "date" data attribute which
                //  is the form of:
                //  - YYYY-MM-DD for elements in the "days" view
                //  - YYYY-MM for elements in the "months" view
                //  - YYYY for elements in the "years" view

                //  so, because we're on a "days" view,
                //  let's find the 24th day using a regular
                //  expression (notice that this will apply to
                //  every 24th day of every month of every year)
                if ($(this).data('date').match(/\-24$/))

                    // and highlight it!
                    $(this).css({
                        backgroundColor:    '#C40000',
                        color:              '#FFF'
                    });

            });

        }

    }

});

`onClear`

Callback function to be executed when the user clicks the Clear button.

The callback function takes no arguments. The this keyword inside the callback function refers to the element the date picker is attached to, as a jQuery object. To get the plugin's properties do properties = this.data('Zebra_DatePicker').

`onClose`

Callback function to be executed when the date picker is closed.

`onOpen`

Callback function to be executed when the date picker is shown.

`onSelect`

Callback function to be executed when a date is selected.

The callback function takes 3 arguments:

the date in the format specified by the format attribute
the date in YYYY-MM-DD format and additionally hours, minutes and seconds if time picker is enabled
the date as a JavaScript Date object

this inside the callback function refers to the element the date picker is attached to, as a jQuery object. To get the plugin's properties do properties = this.data('Zebra_DatePicker').

Methods

First, get a reference to the plugin like

var datepicker = $('selector').data('Zebra_DatePicker');

Then call a method like

datepicker.update();

`clear_date()`

Clears the selected date (if any)

`destroy()`

Removes the plugin from an element

`set_date(date)`

Sets the value of the element the date picker is attached to, to the specified date;

The date must be in the format defined by the format property or a JavaScript Date object.

The date will not be set if it is disabled (either because of disabled_dates or because of direction properties)

`show()`

Shows the date picker (unless the always_visible property is set to true)

`hide()`

Hides the date picker (unless the always_visible property is set to true)

`update([options])`

Updates configuration options at run-time, and recalculates date picker's icon position relative to the parent element. You should call this method whenever you show/hide/reposition the parent element, or alter the parent element's dimensions.

The method accepts an optional argument - an object with configuration options to update:

var datepicker = $('selector').data('Zebra_DatePicker');
datepicker.update({
    direction: 1
});

If you just want to update the icon's position, simply call the method without any arguments:

var datepicker = $('selector').data('Zebra_DatePicker');
datepicker.update();

Global options

If you have multiple date pickers that share common options you can set these options like this:

// this needs to be called only once and does
// not have to be called from within a "ready" block!
$.fn.Zebra_DatePicker.defaults = {
    // any valid options
}

Any options set like this will be applied to all the newly created date picker. Obviously, options set at the creation of any new date picker would overwrite the respective defaults.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Zebra Datepicker

Features

🎂 Support the development of this project

Demo

Requirements

Installation

How to use

Configuration options

Properties

Events

onChange

onClear

onClose

onOpen

onSelect

Methods

clear_date()

destroy()

set_date(date)

show()

hide()

update([options])