date-picker
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);
Displaying
| 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>
Events
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.
|