Docs | MTR Datepicker - The pure JavaScript datepicker library

About

MTR Datepicker is a library written in pure JavaScript which allows you to create great looking and lightweight datepickers for you web apps. It is supported by all of the modern internet browsers and comes with a few customizable themes.

Use these docs to learn how to use it. If you are interested in that "How it is made?" you can check the jsdocs or directly dive into the code. We appreciate your feedback so you can contact us always in the issues section. And don't forget to check the Contributions guide, maybe you can help us to make the datepicker better.

Installation

Get the code

There are two possible ways to include the mtr-datepicker library in your project. You can download the latest stable release form the official site and include it in your templates.

Or if you prefer to be up-to-date with our latest releases with a package manager you can use NPM or Yarn, just type in your Terminal or CMD the following command:

npm install --save mtr-datepicker

or

yarn add mtr-datepicker

Load the library

First you need to load the styles of the datepicker. Put the following lines in the head section of your html file or template:


<link rel="stylesheet" type="text/css" href="dist/mtr-datepicker.min.css">
<link rel="stylesheet" type="text/css" href="dist/mtr-datepicker.default-theme.min.css">

Then you should load the JavaScript, we suggest you to put the lines at the bottom of the body section of your html file or template. That is all, now you are ready to initialize your first datepicker.


<script type="text/javascript" src="dist/mtr-datepicker.min.js"></script>

How to use

To use the loaded scripts just add an element with specific id to your html and then tell the library to make it a datepicker. Here is a simple example:


<div id="first-mtr-datepicker"></div>

<script>
  var config = {
    target: 'first-mtr-datepicker'
  };
  var myDatepicker = new MtrDatepicker(config);
</script>

You can use more advanced datepickers and customize their behavior. To learn how, you should go and read more from the API section of the docs.

API

Init

The datepicker comes with a rich configuration properties. This allows you to make it work the way you want. You can pass an object with configuration settings on initialization of every of your datepickers. And the cool part is that you can use the options combined, here is a list of all of them and their default values. Read the docs to learn more about every one of them.


var config = {
  target:     'id-element',         // ID of HTML element
  timestamp:  CURRENT_TIMESTAMP,    // Starting date
  future:     false,                // Only dates in the future,
  smartHours: false,                // Make a smart switch from AM to PM
  animations: true,                 // NOTE: thew version with disabled animations is not stable

  months: {
    min: 0,
    max: 11,
    step: 1
  },
  minutes: {
    min: 0,
    max: 50,
    step: 10
  }
  years: {
    min: 2000,
    max: 2030,
    step: 1
  }
};

var myDatepicker = new MtrDatepicker(config);

Default

If you want to initialize the datepicker with its default behavior you don't have to do anything special. Just refer to the How to use section.

Set starting date

The default initialization behavior of the datepicker sets the current date as starting one. If you want you can change this and make it to start with custom date simply by adding a timestamp. Take a look at the example:


<div id="start-date-mtr-datepicker"></div>

<script>
  var initDate = new Date(2010, 10, 21);
  var config = {
    target: 'start-date-mtr-datepicker',
    timestamp: initDate.getTime()
  };
  var myDatepicker = new MtrDatepicker(config);
</script>

Only future dates

Sometimes you need the users to be able to select only dates in the future. Don't worry, mtr-datepicker has build-in feature for this, just pass the future parameter during the initialization and it is done.


<div id="only-future-dates-mtr-datepicker"></div>

<script>
  var config = {
    target: 'only-future-dates-mtr-datepicker',
    future: true
  };
  var myDatepicker = new MtrDatepicker(config);
</script>

Smart AM/PM switching

Maybe you have noticed that when the hours are changing the AM/PM switch is not affected. Make your datepicker smarter and initialize it with the smartHours parameter and the AM/PM switch will change automatically with changes of the hours slider.


<div id="smart-hours-mtr-datepicker"></div>

<script>
  var config = {
    target: 'smart-hours-mtr-datepicker',
    smartHours: true
  };
  var myDatepicker = new MtrDatepicker(config);
</script>

Disable AM/PM (use 24 hours time format)

If you want to use the full 24 hours time format you can disable the AM/PM behavior easily. Just initialize your datepicker with the disableAmPm parameter and the AM/PM switch will be not present anymore.


<div id="disable-ampm-mtr-datepicker"></div>

<script>
  var config = {
    target: 'disable-ampm-mtr-datepicker',
    disableAmPm: true
  };
  var myDatepicker = new MtrDatepicker(config);
</script>

Disable date picker

If you want to use only the time fields you can disable the Date Picker behavior easily. Just initialize your datepicker with the datepicker parameter and control the visibility of the date related fields.


<div id="disable-datepicker-mtr-datepicker"></div>

<script>
  var config = {
    target: 'disable-datepicker-mtr-datepicker',
    datepicker: false
  };
  var myDatepicker = new MtrDatepicker(config);
</script>

Change date picker order

If you want you can change the order of the Date Picker fields easily. Just initialize your datepicker with the datepicker parameter and control provide the date related fields in the exact order you want to be rendered.


<div id="reorder-datepicker-mtr-datepicker"></div>

<script>
  var config = {
    target: 'reorder-datepicker-mtr-datepicker',
    datepicker: ['dates', 'months', 'years']
  };
  var myDatepicker = new MtrDatepicker(config);
</script>

Disable time picker

If you want to use only the date fields you can disable the Time Picker behavior easily. Just initialize your datepicker with the timepicker parameter and control the visibility of the time related fields.


<div id="disable-timepicker-mtr-datepicker"></div>

<script>
  var config = {
    target: 'disable-timepicker-mtr-datepicker',
    timepicker: false
  };
  var myDatepicker = new MtrDatepicker(config);
</script>

Output

Now, when you already know how to init the datepicker in the way you want we should show you how to get the selected date in the best format for you. The datepicker is written in JavaScript and because of this we support all of the default methods for getting output of a date. Here is a complete list with all of the function which you can use and of course a simple example:

toDateString() - Wed Sep 23 2015
toGMTString() - Wed, 23 Sep 2015 08:43:47 GMT
toISOString() - 2015-09-23T08:43:47.284Z
toLocaleDateString() - 9/23/2015
toLocaleString() - 9/23/2015, 11:43:47 AM
toLocaleTimeString() - 11:43:47 AM
toString() - Wed Sep 23 2015 11:43:47 GMT+0300 (EEST)
toTimeString() - 11:43:47 GMT+0300 (EEST)
toUTCString() - Wed, 23 Sep 2015 08:43:47 GMT


<script>
  var config = {
    target: 'mtr-datepicker',
  };
  var myDatepicker = new MtrDatepicker(config);
  var datepickerOutput = myDatepicker.toLocaleString();

  console.log(datepickerOutput);
</script>

format()

If you need more specific data from the datepicker you can use the format() method. Maybe you are familiar with it from other languages and libraries. You can specify the format of the output data, just pass it as a string. Here is a list of all supported parameters and their meaning:

Months

M - month without leading zero (1-12)
MM - month with leading zero (01-12)
MMM - month name (Jan-Dec)

Dates

D - date without leading zero (1-31)
DD - month with leading zero (01-31)

Years

Y, YYYY - year with 4 digits
YY - year with 2 digits

Hours

h - hour without leading zero (1-12)
hh - hour with leading zero (01-12)

Minutes

m - minutes without leading zero (0-59)
mm - minutes with leading zero (00-59)

AM/PM

a - am/pm
A - AM/PM

Here are some simple examples how to use the format() function:


<script>
  var config = {
    target: 'mtr-datepicker',
  };
  var myDatepicker = new MtrDatepicker(config);
  var datepickerOutput = myDatepicker.format('D.M.Y h:m A');

  console.log(datepickerOutput);
</script>

Events

On change

Sometimes you want to be notified when the datepicker values are changing. For this purpose the datepicker comes with build-in events and you can use them easy.
You can register event listeners on change of the following properties.

hour
minute
ampm
time
day
month
year
date
all

Here is an example how to listen for changes on all of the time fields.


<script>
var config = {
  target: 'mtr-datepicker',
};

var demoDatepicker = new MtrDatepicker(config);
demoDatepicker.onChange('time', function() {
  // put you code here
});
</script>

Before change

If you want you can listen for changes just before they are made to the datepicker fields. You can listen for the same properties in the onChange event. Here is a simple example how to add your listeners for changes in all date fields:


<script>
var config = {
  target: 'mtr-datepicker',
};

var demoDatepicker = new MtrDatepicker(config);
demoDatepicker.beforeChange('date', function() {
  // put you code here
});
</script>

Plugins

Sometimes you need more flexibility and powerful features in order to use the datepicker in your project. Here comes our plugins - developed to extend the datepicker with new features which are not built by default. For now we don't offer rich choice but the number of our plugins will increase in the future.

Timezones

Our timezones plugin extends the datepicker in order to use it with different timezones. As you already may know - JavaScript doesn't support timezones at all.. or it support some type of a timezones behavior but it's not what you expect. The idea of our datepicker is to use only pure JS so we cannot use any third party libraries and we have done the tricky job with this plugin.

How to use

In order to use our timezones plugin you should load it before the datepicker itself. Then you can use the datepicker constructor to set the required timezone. To do that you have 3 different ways described bellow. Just to be sure that you loaded the plugin the correct way - here is a brief example:


<script type="text/javascript" src="dist/mtr-datepicker-timezones.min.js"></script>
<script type="text/javascript" src="dist/mtr-datepicker.min.js"></script>

<script>
  datepicker = new MtrDatepicker({
    target: 'datepicker',
    utcTimezone: 'Europe/London'
  });
</script>

UTC Init

On of the ways to init the datepicker to work with a specific timezone is to pass its UTC string representation to the constructor using the utcTimezone parameter. Here is a brief example how to do that:


<script>
  datepicker = new MtrDatepicker({
    target: 'datepicker',
    utcTimezone: 'DST'
  });
</script>

Timezone init

You can use a string representation of the timezone too, again combinate it with the utcTimezone parameter:


<script>
  datepicker = new MtrDatepicker({
    target: 'datepicker',
    utcTimezone: 'Europe/Sofia'
  });
</script>

UTC offset init

The utcTimezone can accept one more input type - a number representation of the timezone offset according to UTC:


<script>
  datepicker = new MtrDatepicker({
    target: 'datepicker',
    utcTimezone: -6
  });
</script>

Contribute

We will appreciate it if you want to support our project and contribute to make it better. You can read our contribution guide in GitHub or refer to this one here in the docs. In order to change the source of the datepicker you have to install the following software to your PC or Mac:

Our guidelines

Please, if you want to contribute to our project be sure that your code comply with these guidelines:

2 spaces for indentation, not tabs please.
Please check that your code will pass jshint code standards, grunt jshint will run this for you.
Please ensure you're changing the individual files in /scripts or /styles/less, not the concatenated outputs in /dist directory
Please keep pull requests concise, and document new functionality with jsdocs and usage docs
Consider whether your changes are useful for all users

How to build

Get the source

To prepare your environment you should follow these simple steps First you need to fork our repository in GitHub and then clone it to your PC or Mac with the GitHub app for your platform or type the following command in your Terminal or CMD.


git clone https://github.com/[YOUR-USERNAME]/mtr-datepicker.git

WARNING: Fix the url and place your username when you start cloning your forked repository.

NOTE: We don't obligate you to fork our repo. You can just download the code but if you want to submit your changes later it will be easy for you to send us a pull request. Because of this we suggest you to fork our repository.

Setup packages

Download the required development packages with npm. Just type the following command in your Terminal or CMD. It will take a while to download all of the packages so don't terminate it and be patient.

npm install

Lets build the code

That's all, you are ready to make changes in the code. Probably you'll want to build the source and see in action the changes which you made. As we said in the beginning, the datepicker is build with Grunt and comes with a setup for this. Just type the following command in your Terminal or CMD and then open http://localhost:8080/demo.html in your browser.


grunt

Running "connect:server" (connect) task
Started connect web server on http://localhost:8080

Running "watch" task
Waiting...

Run the tests

Yup, the datepicker has some tests and it will be good to run them after finishing your changes, we don't want to break the build. So to run the test you just have to type the following command in your Terminal or CMD.

node_modules/karma/bin/karma start karma.conf.js --single-run

Write some tests

If you want you can add more tests and increase the code coverage of the project, it will be great. We are using the Jasmine framework and running the tests on all supported browsers with the Karma runner. Everything is setup and ready for use but if you are not familiar with writing tests with these tools we suggest you to read something about them before you start.

When you write some tests you can check their execution on the following url http://localhost:8080/tests/SpecRunner.html.

NOTE: Be sure that you have started the server with Grunt before trying to visit the web tests runner. How to start Grunt?

License

MTR Datepicker is open source and available under the GPL license.

About

Installation

Get the code

Load the library

How to use

API

Init

Default

Set starting date

Only future dates

Smart AM/PM switching

Disable AM/PM (use 24 hours time format)

Disable date picker

Change date picker order

Disable time picker

Output

format()

Events

On change

Before change

Plugins

Timezones

How to use

UTC Init

Timezone init

UTC offset init

Contribute

Our guidelines

How to build

Get the source

Setup packages

Lets build the code

Run the tests

Write some tests

License

Getting Started

API

Plugins

Contribute