This chapter focuses on the jQuery UI datepicker widget, which provides a convenient visual mechanism for helping users select dates. Getting date information from users as text is notoriously problematic because of the wide range of formats in which dates can be expressed. The datepicker widget can make it easier for the user to select a date and provide the information to you in a way that is more consistent and less prone to errors. Table 21-1 provides the summary for this chapter.
You can use the datepicker in two basic ways. The most common is to attach the widget to an input
element, using the datapicker
method. There is no immediate visual change to the input
, but when the element gains the focus (because the user either tabs from other elements or clicks the input
field), the datepicker pops up to help the user select a date. This is known as a pop-up datepicker. Listing 21-1 shows how you create a pop-up datepicker.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker();
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div class="ui-widget">
<label for="datep">Date: </label><input id="datep"/>
</div>
</form>
</body>
</html>
You can see how focusing on the input element displays the datepicker in Figure 21-1.
When the datepicker pop-up is displayed, the user can choose to enter a date manually or use the datepicker window to select a date. The datepicker pop-up disappears when the input
element loses the focus or when the user hits the Enter or Escape key.
The other way to use the datepicker is to use it inline. To achieve this, you select a div
or span
element using jQuery and then call the datepicker
method. An inline datepicker is visible whenever the underling element is visible. Listing 21-2 provides a demonstration of creating an inline datepicker.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left; margin-right: 10px}
#wrapper > * {float: left}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#inline').datepicker();
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div id="wrapper" class="ui-widget">
<label for="datep">Date: </label><input id="datep"/><span id="inline"></span>
</div>
</form>
</body>
</html>
In this example, I have used a span
element in the document and used this as the target of the datepicker
method. You can see the effect in Figure 21-2.
An inline datepicker can be useful when you don’t want to work with pop-ups. There are some applications where dates are so important that it makes sense to display the datepicker all of the time, but in most cases hiding the pop-up until it is required is more sensible. The problem with hiding and showing an inline datepicker is that the layout of the document has to flex to accommodate the datepicker, which can cause presentation problems. For almost all situations, I find the pop-up datepicker to be more useful.
If you have done any work with dates before, you will understand that they are very complicated to deal with. You see this complexity reflected in the large number of settings supported by the datepicker widget. In the following sections, I describe groups of related settings that can be used to configure the datepicker.
You can use some settings to configure the basic nature of the pop-up and inline datepickers. These are important because they allow you to control the integration of the datepicker widget into the document. Table 21-2 describes these settings.
The most basic setting is also one of the most useful. The defaultDate
setting specifies the date that will be shown when the datepicker is displayed.
If you don’t provide a value for the defaultDate
setting, then the current date will be used. (This is, of course, the date as defined by the user’s system. Time zones, date lines, and misconfiguration can all present the user with a different date from the one you might be expecting to appear.)
Tip This setting is used only if there isn’t a value
attribute for the input
element. If there is, either because you have included the value
attribute in the document or because the user has previously made a selection, then the datepicker uses this value.
If you don’t want today’s date, then you can choose from several different formats to express the date you want to start with. Table 21-3 shows the range of formats and values you can use.
Listing 21-3 shows the use of the defaultDate
setting to specify a date five years in the future.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
defaultDate: "+5y"
});
});
</script>
...
I am writing this chapter in November 2011, and you can see in Figure 21-3 that the +5y
value for the defaultDate
setting focuses the datepicker on November 2016.
You’ll see this format for specifying relative dates again. It is a flexible format that gives a lot of precision. As in the example, you omit any interval that you don’t want to change such that you can use +5y
rather than +0d +0w +0m +5y
. I also like the way you can mix and match negative and positive values for different intervals to zero in on the date you want.
The altField
setting lets you specify an alternative input
element that will be updated when a date selection is made. This is the easiest way of linking an element with an inline datepicker and can be a handy feature when using a pop-up. Listing 21-4 shows the use of the altField
setting as a means of displaying the selection from an inline datepicker.
...
<script type="text/javascript">
$(document).ready(function() {
$('#inline').datepicker({
altField: "#datep"
});
});
</script>
...
In this example, I have used a selector string to identify the element I want to use, but the altField
setting will also accept a jQuery object or a DOM HTMLElement
object. The effect of this example is that the input
element displays the date each time I make a selection using the datepicker.
The showOn
setting lets you control what causes a pop-up datepicker to be shown to the user. There are three allowed values for this setting:
focus
: The pop-up is shown when the input element gains the focus. This is the default.button
: The pop-up is shown when a button is clicked.both
: The pop-up is shown when a button is clicked or when the input gains focus.When you use the button
or both
value, the datepicker widget creates a button
element and adds it to the document immediately after the input
element. Listing 21-5 shows the use of the showOn
setting.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
showOn: "both"
});
});
</script>
...
You can see the button
element in Figure 21-4. Since I used the both
value in this example, the pop-up will be displayed when the user either clicks the button
or focuses on the input
element.
Tip The button that the datepicker widget adds is not a jQuery UI button widget. If you want to keep your buttons consistent, then you will need to select the button
element and call the jQuery UI button
method, as described in Chapter 18.
You can format the button
element using the buttonImage
or buttonText
setting. If you set buttonImage
to a URL, the datepicker widget will use the image in the button
. Alternatively, you can use the buttonText
setting to set a phrase to replace the default content (which is ...
). Listing 21-6 shows the use of the buttonText
setting.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
showOn: "both",
buttonText: "Select"
});
});
</script>
...
You can do without the button entirely if you use the buttonImage
and buttonTextOnly
settings together. This causes the datepicker to add an img
element to the document rather than a button. Listing 21-7 provides a demonstration.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left}
#dpcontainer * {vertical-align: middle}
#dpcontainer img {width: 35px;}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
showOn: "both",
buttonImage: "right.png",
buttonImageOnly: true
});
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div id="dpcontainer" class="ui-widget">
<label for="datep">Date: </label><input id="datep"/>
</div>
</form>
</body>
</html>
In this example, I have specified an image called right.png
and set buttonImageOnly
to true
. I have also added some CSS styles to the document to control the appearance of the image relative to the label
and input
elements. The datepicker widget isn’t particularly smart about how it creates the img
element, so you need to compensate to bring the style of the image in line with the rest of the document. You can see the effect of having an image rather than a button in Figure 21-5.
The purpose of the datepicker widget is to allow the user to select a date, but you often want to apply some constraints to the range of dates that are available for selection. Table 21-4 describes the settings that allow you to apply selection constraints to guide the user to a date you can work with.
When set to true
, the constrainInput
setting restricts the characters that can be entered into the input
element to those that are contained in a valid date. The set of characters is dependent on the localization configuration you are using, which I talk more about in the “Localizing Date Selection” section later in this chapter. If you have not localized the datepicker widget, then you can expect the input
element to be restricted so that the user can enter only numbers and the /
character. This setting doesn’t mean that the user can only enter valid dates because a value like 99/99/99
can be entered, but it can help reduce errors. The importance of this setting increases when the showOn
setting is set to button
because the pop-up won’t automatically appear when the input
element gains the focus. Users will typically select from the datepicker when it is presented to them but won’t always realize that a button will display a picker. Every opportunity you give the user to enter a date directly sharply increases the chances you have to process a badly formatted value. Listing 21-8 shows the use of the constrainInput
setting.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left; margin-right: 10px}
#wrapper > * {float: left}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
constrainInput: true,
minDate: "-3",
maxDate: "+1"
});
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div id="wrapper" class="ui-widget">
<label for="datep">Date: </label><input id="datep"/><span id="inline"></span>
</div>
</form>
</body>
</html>
The constrainInput
setting is true
by default, so I have added values for the minDate
and maxDate
settings as well, just to make the example a little more interesting. These settings allow you to specify the earliest and latest dates that the user can select. As with the defaultDate
setting I showed you in the previous section, you can specify the dates for the minDate
and maxDate
settings as null
(no date), a Date
object, a number
of days, or a relative date string. In this example, I used the number option that specifies the number of days relative to today. In Figure 21-6, you can see that the datepicker widget disables any date that the user cannot select.
Tip Notice that the previous and next buttons are disabled automatically when they are not required. These are the buttons at the top left and top right of the datepicker that allow the user to move to the previous and next months. In Figure 21-6, all of the dates that the user can select are in the current month, so both of these buttons are disabled. You can hide, rather than disable, buttons in this situation by setting hideIfNoPrevNext
to true
.
The minDate
need not be in past, the maxDate
need not be in the future, and you don’t have to provide values for both settings. If you need the user to pick a date for which there is some kind of lead time, you can specify a future date for the minDate
setting to prevent dates from being selected that are inside the period you need to prepare, as shown in Listing 21-9.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
minDate: "+7"
});
});
</script>
...
In this example, I have specified that the user cannot select any date that occurs sooner than a week from today. There is no maxDate
value, meaning that any future date after a week from now can be selected. You can see the result in Figure 21-7. Notice that the next button (which allows the user to navigate to the next month) is enabled in this figure, but the previous button is disabled (since there are no dates in the past that the user is allowed to select).
Tip The minDate
and maxDate
settings work in conjunction with the defaultDate
setting, meaning that you can specify ranges of dates relative to a date that is not today.
The datepicker setting allows you to specify how many months are displayed to the user through the numberOfMonths
setting. You can specify either a number of months or a two-element array, which specifies the size of a grid of months. Listing 21-10 shows the array-based approach, which I find is most suited to inline datepickers because the grid is often too big to use as a pop-up (I’ll explain why in a moment).
...
<script type="text/javascript">
$(document).ready(function() {
$('#inline').datepicker({
numberOfMonths: [1, 3]
});
});
</script>
...
In this example, I have specified a grid of one month high and three months wide. You can see the effect in Figure 21-8.
Tip The two-element array [1, 3]
is equivalent to the numeric value 3
. When you provide a number for the numberOfMonths
setting, the datepicker displays the specified number of months in a single row.
The reason that I rarely use this feature with pop-up datepickers is that a large grid requires assumptions about the size of the user’s browser window and display. The datepicker pop-up isn’t an operating system dialog box. It is a carefully formatted HTML element that is displayed as part of the HTML document. This means that when a large datepicker is displayed on a small screen or in a small browser window, much of the detail is displaced off the edge of the screen. Listing 21-11 shows a grid of months applied to a pop-up datepicker.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
numberOfMonths: [1, 3]
});
});
</script>
...
You can see the result in Figure 21-9. Not only are many of the available dates hidden from the user, but the next button (which allows the user to advance the displayed months) is off the screen as well.
You can change the position of the selected date in a multimonth datepicker using the showCurrentAtPos
setting. As you can see in Figure 21-9, the default is to display the current month first, followed by the next two months in the future. The showCurrentAtPos
setting takes a zero-based index value that specifies the location where the current month should be displayed. This is a very handy feature if you need to allow the user to select dates on either side of today. Listing 21-12 shows the use of this setting.
...
<script type="text/javascript">
$(document).ready(function() {
$('#inline').datepicker({
numberOfMonths: 3,
showCurrentAtPos: 1
});
});
</script>
...
I have specified that the current date should be shown in the middle of the three months shown by the datepicker. You can see the result in Figure 21-10.
You can replace the month and year in the header of the datepicker header with drop-down menus that provide direct access to months and years. This can be a useful shortcut for users when there is a large date range to select from. The settings that control these features are changeMonth
and changeYear
. A true
value for these settings enables the corresponding menu, and the menus can be enabled independently of one another. Listing 21-13 shows the use of these settings.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
changeMonth: true,
changeYear: true,
yearRange: "-1:+2"
});
});
</script>
...
In this script, I have enabled both drop-down menus. I have also used the yearRange
setting to limit the range of years that the user can navigate to. In this example, I have specified a value of -1:+2
, which means that the user can select one year back from today through to two years into the future. Since I am writing this chapter in 2011, the range of years that the user is presented with is 2010 to 2013. You can see how the menus are displayed (and how the year range appears) in Figure 21-10.
Tip You can also supply a range of actual years for the yearRange
setting. I could have achieved the same result in Figure 21-11 with a value of 2010:2013
.
You can use a number of settings to tailor the appearance of the datepicker when it is displayed to the user. For general date selection purposes, the default appearance that you have seen in earlier examples is usually suitable, but the ability to tweak the appearance to suit the requirements of a web application is extremely useful. Table 21-5 describes the appearance-related settings.
For some applications, knowing which week of the year a date falls in is essential. This is often the case in budget management applications, for example. The jQuery UI datepicker can display week information, configured through the showWeek
and weekHeader
settings, as shown in Listing 21-14.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
showWeek: true,
weekHeader: "Week"
});
});
</script>
...
When the showWeek
setting is true
, the datepicker displays a column that shows week numbers. You can use the weekHeader
setting to change the title of the week column from the default, Wk
. In the example, I have enabled the week column and changed the title to Week
. You can see the result in Figure 21-12.
The datepicker displays only the dates in the current month by default. This means there are blank entries in the date grid before and after the range of dates. You can show dates from the previous and next months by using a value of true
for the showOtherMonth
setting, as shown in Listing 21-15.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
showOtherMonths: true
});
});
</script>
...
You can see the result in Figure 21-13. The dates from the other months cannot be selected unless selectOtherMonths
is set to true
.
When true
, the showButtonBar
setting enables a button bar at the bottom of the datepicker window. When using a pop-up datepicker, the button bar contains Today and Done buttons. The Today button jumps back to the current date, and the Done button dismisses the pop-up. You can see the buttons Figure 21-14. When part of an inline datepicker, only the Today button is shown.
Tip You can change the text used for the Today and Done buttons using the currentText
and closeText
settings.
When true
, the gotoCurrent
setting will return the datepicker to the currently selected date rather than today’s date. This is useful when you have configured the datepicker with the defaultDate
setting. It doesn’t always make sense to return to the current date if the purpose of the date selection is related to historical or future events. Listing 21-16 contains an example.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
showButtonPanel: true,
gotoCurrent: true,
defaultDate: "+1m +1y"
}).val("12/25/2012");
});
</script>
...
Note that the gotoCurrent
setting causes the button to go to the selected date. In this example, this will be taken from the value
attribute of the input
element, but if the user selects another date and later opens the datepicker again, the button will return to the date the user selected, rather than the dates you specified.
You can use the appendText
setting to provide the user with a hint about the date format that you are expecting. Listing 21-17 provides a demonstration.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
appendText: '(mm/dd/yyyy)'
});
});
</script>
...
The datepicker inserts the text you specify into the document, as shown in Figure 21-15.
This setting is most useful when you rely on a button to make the pop-up datepicker appear. When the user is free to enter the text without the datepicker, then the hint you give them about the format can significantly reduce the errors you have to deal with (which is good for you and less frustrating for the user).
Recently, I have started using the HTML5 placeholder
attribute for input
elements as a neater alternative to the datepicker appendTo
setting. Listing 21-18 provides a demonstration.
...
<script type="text/javascript">
$(document).ready(function() {
$('#datep').attr("placeholder", "mm/dd/yyyy").datepicker();
});
</script>
...
Obviously, this requires the user to have an HTML5 browser, but the effect is more elegant. The user is presented with the format hint in grayed-out text that disappears as soon as they start typing. I prefer this because it is more closely associated the formatting hint with the input
element, and it doesn’t require space in the document layout. You can see how the placeholder is displayed in Google Chrome in Figure 21-16.
The datepicker widget supports the methods that are shown in Table 21-6.
I find that the getDate
and setDate
methods most useful when I am using multiple inline date pickers to allow the user to select a date range. In this situation, I don’t want to display the selected dates in input
elements. I want to display just the number of days between the first and second dates. Listing 21-19 provides a demonstration.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left; margin-right: 10px}
#wrapper > * {float: left}
#result {margin: auto; padding: 10px; width: 200px; clear: left}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#result').hide();
$('#dateStart, #dateEnd').datepicker({
minDate: "-7d",
maxDate: "+7d",
onSelect: function(date, datepicker) {
if (datepicker.id == "dateStart") {
$('#dateEnd').datepicker("setDate", date)
.datepicker("enable").datepicker("option", "minDate", date)
}
if (!$('#dateEnd').datepicker("isDisabled")) {
var startDate = $('#dateStart').datepicker("getDate");
var endDate = $('#dateEnd').datepicker("getDate");
var diff = endDate.getDate() - startDate.getDate();
$('#dayCount').text(diff).parent().show();
}
}
}).filter("#dateEnd").datepicker("disable");
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div id="wrapper" class="ui-widget">
<label for="dateStart">Start: </label><span id="dateStart"></span>
<label for="dateEnd">End: </label><span id="dateEnd"></span>
</div>
<div id="result" class="ui-widget">
Number of Days: <span id="dayCount"></span>
</div>
</form>
</body>
</html>
There are two datepickers in this example, the second of which is disabled when the document is first loaded. I use the onSelect
event (which I explain later in this chapter) to respond to the user making date selections. When the user makes a selection in the first datepicker, I use the setDate
method to prepare the second datepicker and the getDate
method to get the dates from both datepicker in order to work out the number of days between the first and second selected dates (to keep this example simple, I have done a simple comparison that assumes that both dates are in the same month). You can see how this document is displayed in the browser in Figure 21-17.
You can use the show
and hide
methods to programmatically control the presence of a pop-up datepicker on the screen. This can be useful if you want to associate the datepicker with something other than the focus of the input
element or the button
that the datepicker widget creates. I am not much of a fan of letting the datepicker create a button in the document, so I occasionally find myself using these methods to control the datepicker from a button I have added myself, as demonstrated in Listing 21-20.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left; margin-right: 10px}
#wrapper > * {float: left}
label {padding: 4px; text-align: right; width: auto}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker();
$('button').click(function(e) {
e.preventDefault();
$('#datep').datepicker("show");
setTimeout(function() {
$('#datep').datepicker("hide");
}, 5000)
})
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div id="wrapper" class="ui-widget">
<label for="datep">Date: </label><input id="datep"/><span id="inline"></span>
<button>Datepicker</button>
</div>
</form>
</body>
</html>
I call the datepicker show
method when the button is clicked. I don’t often use the hide
method because I want the user to be able to dismiss the pop-up when they have made a selection, but for completeness, I have used the setTimeout
function so that the pop-up is programmatically dismissed five seconds after the button has been pressed.
Like all jQuery UI widgets, the datepicker supports a set of events that allow you to receive notifications of important changes. These events are described in Table 21-7.
I am not going to demonstrate the onSelect
method again because I have already used it in a couple of examples, including the one in the previous section. I do want to mention that the arguments passed to the handler function for this event are a string representation of the selected date and the datepicker that has triggered the event.
The onChangeMonthYear
event allows you to respond when the user selects a new month or year, either from the drop-down menus enabled by the changeMonth
and changeYear
settings or through the previous and next buttons. Listing 21-21 shows how you can use this event to keep two datepickers consistent.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left; margin-right: 10px}
#wrapper > * {float: left}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#dateStart, #dateEnd').datepicker({
onSelect: function(date, datepicker) {
if (datepicker.id == "dateStart") {
$('#dateEnd').datepicker("setDate", date)
}
},
onChangeMonthYear: function(year, month, datepicker) {
if (datepicker.id == "dateStart") {
var newDate = new Date();
newDate.setMonth(month -1);
newDate.setYear(year);
$('#dateEnd').datepicker("setDate", newDate);
}
}
})
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div id="wrapper" class="ui-widget">
<label for="dateStart">Start: </label><span id="dateStart"></span>
<label for="dateEnd">End: </label><span id="dateEnd"></span>
</div>
</form>
</body>
</html>
The three arguments to the function for this event are the displayed year, the displayed month, and the datepicker that triggered the event. The this
variable is set to the input
element for pop-up datepickers. When the user navigates to a new month or year on the first datepicker, I set the date on the second datepicker to keep them in sync.
Notice that the datepicker widget represents January as month 1 while the JavaScript Date
object uses 0. This is why I have to make an ugly adjustment like this:
newDate.setMonth(month -1);
when I am creating the date I want displayed in the second datepicker.
You can use the onClose
method to respond to the pop-up datepicker being closed. This event is triggered even when the user has not made a date selection. The arguments to the handler function are a string representation of the date (or the empty string if the user dismissed the datepicker without making a selection) and the datepicker that triggered the event. Listing 21-22 shows a simple response to this event.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left; margin-right: 10px}
#wrapper > * {float: left}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#datep').datepicker({
onClose: function(date, datepicker) {
if (date != "") {
alert("Selected: " + date);
}
}
});
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div id="wrapper" class="ui-widget">
<label for="datep">Date: </label><input id="datep"/>
</div>
</form>
</body>
</html>
In this example, I display an alert box to the user displaying the selection, if one has been made. I must admit that I have never found myself using this event in a real project; the onSelect
event is the one that I find most useful.
The jQuery UI datepicker has some very comprehensive support for the different date formats that are used around the world. jQuery UI supports 61 localizations. To use them, you need to import an additional JavaScript script into your document and tell the datepicker which locale you want to use. Listing 21-23 provides an example.
<!DOCTYPE html>
<html>
<head>
<title>Example</title>
<script src="jquery-1.7.js" type="text/javascript"></script>
<script src="jquery-ui-1.8.16.custom.js" type="text/javascript"></script>
<script src="jquery-ui-i18n.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="styles.css"/>
<link rel="stylesheet" type="text/css" href="jquery-ui-1.8.16.custom.css"/>
<style type="text/css">
input {width: 200px; text-align: left; margin-right: 10px}
#wrapper > * {float: left}
</style>
<script type="text/javascript">
$(document).ready(function() {
$('#inline').datepicker($.datepicker.regional["es"]);
});
</script>
</head>
<body>
<h1>Jacqui's Flower Shop</h1>
<form method="post" action="http://node.jacquisflowershop.com/order">
<div id="wrapper" class="ui-widget">
<label for="datep">Date: </label><input id="datep"/><span id="inline"></span>
</div>
</form>
</body>
</html>
The jquery-ui-i18n.js
file can be found in the development-bundle/ui/i18n
folder of the customized jQuery UI download you created in Chapter 17. Copy this file into place alongside the main jQuery and jQuery UI script files and add the following to your document:
<script src="jquery-ui-i18n.js" type="text/javascript"></script>
You can specify the locale to use for the datepicker when you create it, as follows:
$('#inline').datepicker($.datepicker.regional["es"]);
This is a messy syntax, but it allows you to specify the localized formats you want. In this example, I have specified es
, which means that I will be using the Spanish date formats. You can see the result in Figure 21-18.
Tip You can create custom localizations if you need date conventions that are not currently supported by jQuery UI. See http://docs.jquery.com/UI/Datepicker/Localization
for details.
My advice for localization is that it should be done properly or not at all. This means going far beyond just date formats and presenting the user with an interface that fully follows language, address, gender, currency, time, and every other local convention. Users find it jarring if you localize only part of a web application or following conventions inconsistently. To properly localize an application, you should hire an individual or a company that specializes in such work. There are so many ways to go wrong that you are doomed to fail without professional support.
If you find yourself trying to localize an application using Google Translate (which is not uncommon), then I recommend you just deliver the application using U.S. English and U.S. localization conventions. This limits your customer base to those who are familiar with U.S. variants on spelling, dates, currency, and so on, but at least you will avoid the train wreck that almost always arises when ad hoc localization is attempted.
In this chapter, I showed you the workings of the jQuery UI datepicker widget, which you can use to assist the user select dates. The datepicker is a very flexible widget that allows you to tailor the way that date selections are made and the appearance of the datepicker. My own experience with datepickers is that they are invaluable for reducing the number of formatting problems I have to deal with when requesting date information from users.
3.133.133.233