A simple lightweight date-picker, with no external dependencies

There are a number of external functions on the DatePicker, that allows for some measure of control.

When it comes to the look-and-feel, even more control can be achieved by overriding the css.

Exposed non-public methods

There are more exposed methods than should be used normally; they are exposed for testing purposes to allow unit tests to get into the system, and for extreme flexibility, where a developer might want to override standard functions.

These methods will not be covered here, but can instead be found by looking at the code.

Exposed methods

The methods that are exposed as public, and thus relatively stable, are described below.

Static methods

The following methods are currently available directly on the constructor, without requiring a new instance first.

formatDate(date, format) Returns a string-version of the date based on the given format.
parseDate(dateString, format) Parses a string and returns a date based on the given format.

They are called in the following fashion:

var date = new Date()
DatePicker.formatDate(date, 'y-m-d');

Creating the date-picker

The constructor can take the following options:

elm An element to bind to. This can be a real DOM element or a CSS selector pointing at an element.
It is an alternativ to passing the element through #show([selector]) or #toggle([selector]).
dateFormat A format-string signifying how the code should interpret and print out dates in input-fields.
It supports the following keys (example date being 2012/05/07):
d Day with leading zero (07)
D Day without leading zero (7)
m Month with leading zero (05)
M Month without leading zero (5)
y Year with 4 digits (2012)
Y Year with 2 digits (12)
Any other characters will be printed as listed. It defaults to y/m/d.
weekStart A number signifying the first day of the week. It goes from 0 (sunday) to 6 (saturday) and defaults to 1 (monday). It corresponds to calling Date#getDay() on a javascript date object.
weekdays A list of localized day-names that should be shown above the day-cells. It should start with sunday on index 0, and end with saturday on index 6. It should not be much more than 2 letters of text, as that is approximately what there is room for. It defaults to [ 'su', 'mo', 'tu', 'we', 'th', 'fr', 'sa' ].
months A localized list of month names. It starts with January on index 0 and ends with December on index 11. It defaults to [ 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' ].
buttons Localized texts for the three buttons in the UI (Next month, previous month, close). It defaults to { next: 'Next', prev: 'Prev', close: '×' }. Empty strings are perfectly acceptable, if CSS will be controlling the look (for example with background images).
date The date to initialize the date-picker with. It defaults to the current date, or if bound to an input-element, the parsed version of the input-value.
floatingOverlay A bool telling if the floating date picker should put an overlay behind that closes it when clicked. If false (the default), it will only close when a date is selected, the user clicks the close button, or #hide() or #toggle() is called via the API.
It is only applicable if the date picker is bound to an input-element, and thus floating.

It is used in this fashion:

var options =
    { dateFormat: 'y-m-d'
    , buttons: { next: '→', prev: '←', close: 'X' }
var dp = new DatePicker(options);


show([selector]) Shows the date picker, and attaches it to the last given element. Alternatively, an element or css-selector can be supplied for the picker to attach to.
hide() Hides the date picker.
toggle([selector]) Toggles between show() and hide() based on the current state. If the picker is currently showing, and selector refers to a different element, it will show at that new element instead of hiding.
render() Creates the picker with DOM nodes and returns a document-fragment with the contents. It will not be attached to anything by render(). Internally, this is done by show().

The #toggle() method can be used in the following fashion:

<input name=date>
<button onclick="dp.toggle('input[name=date]');">Toggle</button>


The way to get information back out of the DatePicker, especially based on user actions, is through events. It is possible to register and unregister events using the on() and off() functions as shown below:

on(event, callback) Adds a callback for an event. It throws if callback is not a function.
off(event, callback) Removes the specified callback for the named event.
emit(event, [parameters, ..]) Sends the event to all listeners, passing the parameters as well.
trigger(event, [parameters, ..]) Synonym for emit()

The DatePicker currently emits the following events:

change When a user selects a date. If the DatePicker is attached to an input, this will happen just after the input have been updated.
show Emitted after the date-picker appears, or is moved to a new container. This is bound to the show() function.
hide Emitted after the date-picker is hidden. This is bound to the hide() function.