Datebalks

This is the home of datebalks: a Rails plugin that allows you to create date fields with pop-up calendars attached and that support datebocks style date entry. Why use datebalks instead of datebocks? Because datebalks is not a Rails Engine. It's just a javascript file with a little bitmap. The heavy lifting calendar component is non other than the excellent dynarch calendar. You can think of datebocks as a lean and mean datebocks.

Examples

The following are but a few examples of the strings that a datebalks field can parse: Today, tod, tomorrow, tom, yesterday, 6, 6th, 6th October, Feb 3rd, 10th Feb 2004, Februrary 14th, 12 feb, 1 ja, mon, Friday, next Friday, next fri, next m, last Monday, last mon, 2004-8-8, 2004-04-04, 24/1/2005, 26/4, 10-24-2005, Next Week, Last Year, Next Month, 18.11.2004, 2 years ago, in 6 months...

Motivation

I wanted a fast way to capture a date field and ideally it had to be done without the mouse. Having a DHTML calendar handy was also a definite must. Looking around on the web I quickly found datebocks. I was excited. It was exactly what I wanted in terms of feature-set. The only thing I disliked was the idea of using a Rails Engine for something that seemed so trivial. Rails Engine also didn't play well with Edge Rails. So this got me thinking... How can I reproduce the functionality without the weight of the engine? Datebalks (a tribute to it’s parent) was my answer.

So what are the main advantages of datebalks over it's parent?

Works outside of rails without any changes
Is easier to deploy
Thanks to lowpro it’s non-intrusive

To be fair, I have never really used datebocks and there are many features that are present that datebalks doesn’t (and probably will not) have out-of-the-box such as auto-rollover and programatic formatting of dates. Yet another reason for calling datebalks is a “slimmer” datebocks.

Installation

For the ultimate datebalks experience I suggest that you start by installing the excellent lowpro library, which gives you the ablity to add behaviour to DOM objects in an unobtrusive way. Then, to install datebalks just issue the following command from your Rails application directory:

script/plugin install svn://rubyforge.org/var/svn/datebalks/trunk

Using Datebalks

The first thing to do when you intend to use datebalks on a page is to include the necessary javascript. Here I'm assuming that lowpro is installed:

<%= javascript_include_tag :defaults,'lowpro' %>
<%= javascript_include_tag 'calendar','calendar-setup','calendar-en' %>
<%= javascript_include_tag 'datebalks' %>

In your webpage, add an input with a datebalks class like this:

<input class="datebalks" name="the_date" />

That’s it. There is no step three! The low-pro bit will take care of adding the necessary pieces of HTML to make it look good (with a bit of your CSS help of course) as well as attach an observer to the input field so that the text you type in there is parsed automatically.

How Does it Work?

Datebalks is a small parser written in Javascript to which I've added a pinch of DHTML: the dynarch calendar and a dash of Low-pro love for unobtrusive elegance. Lowpro just scans the page for input fields with a datebalks class. For each such input, lowpro adds a hidden field and links a pop-up calendar to it. As a programmer, all you need to do to get nice date fields is to remember to give them the datebalks class. That's all there is to it!

Under the covers, it transforms your date field a pair of input fields. The original field remains visible but will be renamed by smartly appending a _text to it's name (it's rails aware of course). The other input will be hidden, will be given the original field name and will hold the value of the parsed date in yyyy-mm-dd format. The popup calendar and a text label are also added to provide the user a point and click solution and some feedback.

Changing the Look &Feel

If you need a more customized experience then you can create you own Javascript functions, based on Datebalks.appendPopupAndText() and have low-pro call them instead. By doing this you can really go crazy on the look and feel of your date fields.

Customized & Localized Date Parsers

If you want to localize of the parser it's not that difficult either although this is a bit more involved. For the moment I'll invite you to inspect the code and guess how to do this. It really just boils down to figuring out the various shortcuts and replace the existing regular expressions within the javascript file.

Datebalks Outsite of Rails

If your not using Rails (which is the case of this blog) then there is a little more work to do. You'll need to ensure that both the prototype and low-pro javascript libraries are loaded before including datebalks. You will also need to change a line or to to reflect the correct image path for the calendar.png file.