Specifying the Default Date

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.)

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.

Listing 21-3.  Using the defaultDate Setting

...
<script type="text/javascript">
    $(document).ready(function() {
        $("#datep").datepicker({
            defaultDate: "+5y"
        });
    });
</script>
...

I am writing this chapter in June 2013, and you can see in Figure 21-3 that the +5y value for the defaultDate setting focuses the datepicker on June 2018.

As in the example, you can omit any interval that you don’t want to change such that you can use +5y rather than +0d +0w +0m +5y. You can mix and match negative and positive values for different intervals to zero in on the date you want.

Specifying the Alternate Element

The altField setting specifies an input element that will be updated when you make a date selection. This is the easiest way of linking an input element with an inline datepicker. Listing 21-4 shows the use of the altField setting as a means of displaying the selection from an inline datepicker.

Listing 21-4.  Using the altField Setting with an Inline Datepicker

...
<script type="text/javascript">
    $(document).ready(function() {
        $("#inline").datepicker({
            altField: "#datep"
        });
    });
</script>
...

In Listing 21-4, 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 Document Object Model (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, as shown in Figure 21-4.

Managing the Pop-up Trigger

The showOn setting controls 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.

Listing 21-5.  Using the showOn Setting

...
<script type="text/javascript">
    $(document).ready(function() {
        $("#datep").datepicker({
            showOn: "both"
        });
    });
</script>
...

You can see the button element created by the widget in Figure 21-5. 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.

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.

Listing 21-6.  Using the buttonText Setting

...
<script type="text/javascript">
    $(document).ready(function() {
        $("#datep").datepicker({
            showOn: "both",
            buttonText: "Select"
        });
    });
</script>
...

You can do away with the button text 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.

Listing 21-7.  Using an Image Rather Than a Button

<!DOCTYPE html>
<html>
<head>
    <title>Example</title>
    <script src="jquery-2.0.2.js" type="text/javascript"></script>
    <script src="jquery-ui-1.10.3.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.10.3.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">
      <divid="dpcontainer"class="ui-widget">
        <label for="datep">Date: </label><input id="datep"/>
      </div>
    </form>
</body>
</html>

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 I 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-6.

Limiting the Input Character and Date Range

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 section “Localizing Date Selection.” 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 increases the chances you have to process a badly formatted value. Listing 21-8 shows the use of the constrainInput setting.

Listing 21-8 . Applying Basic Constraints to the Date Selection

<!DOCTYPE html>
<html>
<head>
    <title>Example</title>
    <script src="jquery-2.0.2.js" type="text/javascript"></script>
    <script src="jquery-ui-1.10.3.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.10.3.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: "+5"
            });
        });
    </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 me to specify the earliest and latest dates that the user can select. As with the defaultDate setting I showed you in section “Specifying the Default Date,” I 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 Listing 21-8, I used the number option that specifies the number of days relative to today. In Figure 21-7, you can see that the datepicker widget disables any date that the user cannot select.

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.

Listing 21-9.  Providing One Date Restriction to Create a Delay Window

...
<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-8. 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).

Creating a Multimonth Display

The datepicker 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).

Listing 21-10.  Using the numberofMonths Setting

...
<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-9.

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.

Listing 21-11.  Using the numberOfMonths Setting with 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-10. 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 Figures 21-9 and 21-10, 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 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.

Listing 21-12.  Using the showCurrentAtPos 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-11.

Providing Direct Access to Months and Years

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.

Listing 21-13.  Providing Direct Access to Months and Years Through Drop-Down Menus

...
<script type="text/javascript">
    $(document).ready(function() {
        $("#datep").datepicker({
            changeMonth: true,
            changeYear: true,
            yearRange: "-1:+2"
  
        });
    });
</script>
...

In this listing, 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. I 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 2013, the range of years that the user is presented with is 2012 to 2015. You can see how the menus are displayed (and how the year range appears) in Figure 21-12.

Displaying Weeks

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.

Listing 21-14.  Displaying Week Information in the Datepicker

...
<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-13.

Allowing Bleed Between Months

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.

Listing 21-15.  Allowing Months to Bleed into One Another

...
<script type="text/javascript">
    $(document).ready(function() {
        $("#datep").datepicker({
            showOtherMonths: true
        });
    });
</script>
...

You can see the result in Figure 21-14. The dates from the other months cannot be selected unless selectOtherMonths is set to true.

Using the Button Bar

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 in Figure 21-15. When part of an inline datepicker, only the Today button is shown.

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.

Listing 21-16.  Using the gotoCurrent Setting

...
<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 Listing 21-16, the date 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.

Providing a Format Hint to the User

You can use the appendText setting to provide the user with a hint about the date format that you are expecting. Listing 21-17 demonstrates.

Listing 21-17.  Using the appendText Setting to Provide a Format Hint

...
<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-16.

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 her 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 demonstrates.

Listing 21-18.  Providing a Formatting Hint Using the HTML5 Placeholder Attribute

...
<script type="text/javascript">
    $(document).ready(function() {
        $("#datep").attr("placeholder", "mm/dd/yyyy").datepicker();
    });
</script>
...

Obviously, this requires the user to have an HTML5-enabled browser, but the effect is more elegant. The user is presented with the hint in grayed-out text that disappears as soon as he starts 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-17.