A fully-tested, generic bootstrap component that allows users to specify a date in a variety of different ways. Grab it from Github.
Note that this is not the same as a date-picker! There is, however a good plugin for that here. Perhaps the best way to understand the purpose of this plugin is to look at a few examples.
You want to allow users choose between three fixed dates (e.g. Thanksgiving, Christmas, and Memorial Day), or an arbitrarily specified date.
You want a user to input a date or their age (e.g. if they were born on February 19th, 1988).
Notice that the selector properly translates between different date selection mechanisms.
You want your users to specify a date in terms of the number of years after another user specified date (e.g. the previous example).
This plugin requires the bootstrap CSS framework as well as jQuery.
A normal input tag can be transformed into a date-dropdown as easily as calling
$(".date-dropdown").datedropdown(options);. The
options allow you to customize the variety of ways a user can
input a date.
Underneath the scenes, the original input tag is hidden, and the remaining markup is generated around it. The user makes their date selection however they like, and the hidden input tag is updated with the appropriate date string, formatted as "MM/DD/YYYY". This approach leaves forms with date-input tags unaffected by the use of the widget, as the id and name of the original input tag are preserved.
The underlying HTML manipulation can be demonstrated with a simple example:
options = {
choices: [
{
type: "constant",
label: "Today",
value: new Date(),
default: true,
},
{
type: "pickDate",
label: "Choose a Date",
},
{
type: "yearsAfter",
label: "Your Age",
origin: new Date("2/19/1988"),
},
{
type: "function",
label: "Decades after WW2",
inputToDate: function(text) {
var ww2date = new Date(1939, 9, 1);
var decades = Number(text);
ww2date.setYear(ww2date.getFullYear() + decades*10);
return ww2date;
},
dateToInput: function(date) {
var ww2date = new Date(1939, 9, 1);
return String((date.getFullYear() - ww2date.getFullYear())/10);
}
},
],
};
$('#my-input').datedropdown(options);
Here is the example widget after being transformed.
The initial HTML
<input id="my-input" class="date-dropdown" value="10/10/2012">
is converted to the following output
<div class="datedropdown-container input-prepend">
<input id="my-input" class="date-dropdown" value="10/10/2012" style="display: none;">
<div class="btn-group">
<button class="btn dropdown-toggle" data-toggle="dropdown">
<span>Decades after WW2 </span>
<span class="caret"></span>
</button>
<ul class="dropdown-menu">
<li><a>Today</a></li>
<li><a>Choose a Date</a></li>
<li><a>Your Age</a></li>
<li><a>Decades after WW2</a></li>
</ul>
</div>
<input type="text" class="datedropdown-input" style="width: 74px;">
</div>
| Name | type | default | description |
|---|---|---|---|
| choices | array | options for simple date picker | An array of objects containing the data used to generate the different dropdown choices used to specify how the date will be generated. There are four different types of choices, 'constant', 'pickDate', 'yearsAfter', and 'function'. See table below for more details. |
| showLabels | boolean | true | Control whether the choice labels are displayed in the dropdown button. If false, the labels are only displayed when the user selects the dropdown. |
| dropdownPosition | string | "left" | Options are "left" or "right". Control where choice dropdown button is placed, relative to the input. |
| inputAttrs | object | {} | Any html attributes you want to apply to the generated input tag. Attributes applied using jquery. |
| btnAttrs | object | {} | Any html attributes you want to apply to the generated button tag. Attributes applied using jquery. |
| containerAttrs | object | {} | Any html attributes you want to apply to the generated container div tag. Attributes applied using jquery. |
Each choice object requires a type ("constant", "pickDate",
"yearsAfter", or "function"), and a label. The label is displayed in
the dropdown list. The default option is selected by placing a default key with a true value.
A constant date---no further user interaction required. This will disable the input tag when selected.
This choice type requires you to specify a value, using either a
date object or a date string.
Allow the user to specify a date; no further options required.
Allow the user to specify the number of years after a given date. This can be used for a crude "age" selector.
Requires the reference date to be specified using the
origin option.
Most powerful choice; calculate the age using a function. This
requires two functions, one to convert from a date to the input text
value, and a second to convert back. These two functions are
specified using the inputToDate and
dateToInput keys.
Using the function type you can do a lot of powerful things; for example, if you want to impliment a proper age widget you may want to use datejs with a "function" option so that it properly accounts for leap years and other subtlties.
Initializes the date-dropdown with an optional options object.
Changes the currently selected choice.
The currently selected date will be preserved unless the new choice is "constant" type. If the new choice is of "function" type, then the dateToInput and inputToDate options are used to translate the currently selected date as the user switches between choices.
Re-draw the date-dropdown. This is useful if you have choices of "function" type that need to by synced to other interface elements.
Calling val() on the date-dropdown div will return a
string representation of the currently selected date.
The val() function can also be used to set the current value, unless the current choice is a "constant" type, in which case it doesn't make sense to change the allowed value.
If you need to access the settings for a date-dropdown widget, you
can using jQuery's data() function. You can access the
current date as a javascript Date object using
$("#myDiv").data('settings').currentDate.
| Event | description |
|---|---|
| valueChange | This event fires every time the underlying date represented by the plugin changes. This will typically occurs when the user edits the input tag, however it will also fire if the value is changed programatically. The function is passed a single argument, the new date. |
We are always happy to hear when people are using our code! We If you have any suggestions, or run across bugs or inconsistencies in the documentation, please create a github issue and we will respond as fast as possible!