Note on December 30th, 2012: There were lots of comments and emails to add jQuery Date Plugin code back to github, so I did.

I started engineering a new datepicker from the ground up I’m calling “jQuery UI Datepicker Lite”. Out of my efforts came a new plugin I’m calling jQuery Date. Refer to the date.js file in the github repo.

The date plugin is a very lightweight plugin that provides a fairly simple API for the things I typically need to do with dates and will need for the new datepicker.

1. Parse a date from a string — for example turn 12/25/2010 into a date object. $.date("12/25/2010")
2. Format a date — for example turn a date object / timestamp into a nicer format like “Wednesday December 25, 2010” $.date("12/25/2010).format("dddd, MMMM dd, yyyy")
3. Adjust a date — for example I might want start from today’s date and cycle week to week. $.date().adjust("D", +7).format()

The jQuery date plugin accomplishes these three things by leveraging the official jQuery globalization plugin for date parsing and formatting. This way the date plugin itself can maintain a very lightweight API while still being very functional.

Here are a few examples I’ve put together to show off the plugin’s strengths.

$.date().adjust("M", +3).format("yyyy-dd-MM"); // same as .setFormat("yyyy-dd-MM").format()

$.date().adjust("M", +3).format();

$.date().adjust("D", -3).format();

$.date("October 1, 1984", "MMMM dd, yyyy").adjust("M", 3).adjust("Y", 5).adjust("D", -1).format();

$.preferCulture("ar");

$.date().adjust("M", +3).format();

If I’ve done my job right, you should be able to easily tell what these lines of code would do if you run them. You can always download the demos/date.html file from the jQuery UI Datepicker lite repository and try it for yourself.

So the API is pretty simple. You can use $.date() just like you would normally do new Date(). But instead with $.date() you get all the basic functionality that seems clumsy to do with the JavaScript date object itself as I mentioned…parsing, formatting and adjusting.

Parsing

The $.date(datestring, formatstring) method takes two optional parameters. The datestring, for instance “12/25/2010” and the format “MM/dd/yyyy”. By default it uses the “d” format in whatever calendar you are using with globalization if you don’t specify a formatstring, but pass in a datestring.

Formatting

You can use the default format by just calling $.date().format() or set your own custom format either by parsing it with a format $.date("2010-01-15", "yyyy-dd-MM").format(), use the setFormat method $.date().setFormat("yyyy-dd-MM").format() or just add the format in the format function itself $.date().format("yyyy-dd-MM").

Adjusting

Adjusting is where the chaining happens and this is typically the most often missed thing in all of the JavaScript formatting and parsing libraries I’ve seen. Adjusting dates isn’t really all that difficult in itself, but it does take a bit to learn if you haven’t used JavaScript dates much before.

To adjust a date you can just use the adjust(period, offset) method. For instance, if I want to get 3 months out and 2 days previous from that day, I would just do $.date().adjust("M", +3).adjust("D", -2).format().

Side Note…jQuery Plugin?

Really there is no reason that this date plugin has to live on the jQuery namespace at all, it could be completely decoupled from it since dates have nothing to do with the DOM. But everybody likes jQuery, so this just extends it to add a nice little utility you can leverage when you need to work with dates.

Other considerations

A few other projects have provided great date parsing and formatting. Date.js comes to mind. Where date.js is a wonderful project that provides way more options for parsing, adjusting and formatting it is unfortunately still in beta and hasn’t been touched much since 2008. Also it has no official backing by the jQuery project. I just need something simple, small and lightweight for a building block for the datepicker lite.

jQuery Calendars is likely the most amazing date library on the entire internet since it essentially re-impliments the date object from scratch and then builds all the calendar methods you need on top of it. Believe me, this must have been no easy task…I tried this with Calendar Engine and didn’t get to a complete library like Keith’s. So, I’m still looking at ways where date.js could be an adapter for this library or maybe merge the work Keith has done into jQuery globalization. Either way, this is an amazing project you should be aware of.

Future Development

The datepicker lite and the date plugin is in its very early stages right now so don’t expect much. With the date plugin it is just a super simple plugin to take care of what I need for datepicker lite and covers what I usually need to do with dates. Let me know if you have any comments, feedback or suggestions…of course you can always fork it on github.