Quickstart: Adding a DatePicker (HTML)

Article
08/10/2016

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

If you need to allow users to set a date in your application, for example to schedule an appointment or set the expiration date on a credit card, you can use a DatePicker, which is a part of the Windows Library for JavaScript. The DatePicker displays three controls for month, date, and year. These controls are easy to use with touch support, and they can be styled and configured in several different ways. (Windows only)

Objective: To demonstrate how to use a DatePicker.

Prerequisites

This topic assumes that you can create a basic Windows Runtime app using JavaScript. For instructions on creating your first app, see Creating your first Windows Windows Runtime app using JavaScript.

Instructions

1. Creating a simple DatePicker

As with most WinJS controls, you can create a DatePicker declaratively (as a data-win-control attribute on a <div> element) or imperatively (in a JavaScript code block). In order for the control to appear, you should call WinJS.UI.processAll. If you are using Visual Studio project templates for Windows apps using JavaScript, this is done for you in the activated event handler.

This is how you declare a DatePicker declaratively:

<!DOCTYPE html>
<html>
<head>
  <title>DatePicker Control Example</title>  
  <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet">
  <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
  <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>
</head>
 <body>
     <section>
         <h1> DatePicker Example</h1>
             <h3>Add a DatePicker Declaratively</h3>
             <div id="date" data-win-control="WinJS.UI.DatePicker"></div>
             <script type="text/javascript">
                 WinJS.UI.processAll();
             </script>
     </section>
 </body>
 
</html>

This is how you create a DatePicker in code:

<!DOCTYPE html>
<html>
<head>
<head>
  <title>DatePicker Control Example</title>  
  <link href="//Microsoft.WinJS.2.0/css/ui-dark.css" rel="stylesheet">
  <script src="//Microsoft.WinJS.2.0/js/base.js"></script>
  <script src="//Microsoft.WinJS.2.0/js/ui.js"></script>
  </head>
    <body>      
        <section>
            <h1> DatePicker Example</h1>
                <h3>Add a DatePicker Imperatively</h3>
            <div id="date"></div>
            <script type="text/javascript">
               var dateDiv = document.getElementById("date");
               var datePicker = new WinJS.UI.DatePicker(dateDiv);
            </script>
        </section>
    </body>
</html>

When you build and run your solution, you will see a control that by default displays the current date, with three dropdowns for month, day, and year.

When you use the ui-dark.css file, the DatePicker should look like this: DatePicker dark style

When you use the ui-light.css file, the DatePicker should look like this: DatePicker light style

2. Changing the default date

You can set a different default date declaratively:

<div data-win-control="WinJS.UI.DatePicker" data-win-options="{current:'2/20/2011'}"></div>

You can set the default date in code also:

// "date" is the id of the <div> element
var dateDiv = document.getElementById("date") 
var datePicker = new WinJS.UI.DatePicker(dateDiv, {current: '2/20/2011'});

You can format the date string in all the ways the JavaScript Date object allows. Here are some examples:

'February 20, 2011'
'02/20/2011'
'Sunday, February 20, 2011'

Important You can use any calendar in this release.

3. Specifying different minimum and maximum dates

By default, the earliest year the user can select is the current year minus 100, and the latest year the user can select is the current year plus 100. To change the earliest year to 1900 and the latest year to 2300, you can do the following:

Declaratively

<div data-win-control="WinJS.UI.DatePicker" data-win-options="{minYear: 1900, maxYear: 2300}"></div>

In code

var datePicker = new WinJS.UI.DatePicker(dateDiv);
datePicker.minYear= 1900;
datePicker.maxYear = 2300;

4. Changing the day, month, or year pattern

You can change the pattern of the day, month, or year. By default, the DatePicker displays the full name of the month, a 2-digit day, and a 4-digit year in the en-us locale. You can change this in the following ways.

To change the way the month is displayed


var datePicker = new WinJS.UI.DatePicker(dateDiv);

//change the month to an integer
datePicker.monthPattern = "{month.integer}"; 

//change the month to an abbreviation
datePicker.monthPattern = "{month.abbreviated}";

To change the way the day is displayed


var datePicker = new WinJS.UI.DatePicker(dateDiv);

//display the day without leading zeros
datePicker.datePattern = "{day.integer(1)}";

//display the day of the week along with the date
datePicker.datePattern = 
    "{day.integer(2)} ({dayofweek.abbreviated})";

To change the way the year is displayed


var datePicker = new WinJS.UI.DatePicker(dateDiv);

//diplay the year with only two digits
 datePicker.yearPattern = "{year.abbreviated}";

The following list gives the possible values for the patterns you can use in a DatePicker:

{day.integer} | day.integer(n)}
{dayofweek.full} | {dayofweek.abbreviated} | {dayofweek.abbreviated(n)}
{dayofweek.solo.full} | {dayofweek.solo.abbreviated} | {dayofweek.solo.abbreviated(n)}
{month.full} | {month.abbreviated} | {month.abbreviated(n)}
{month.solo.full} | {month.solo.abbreviated} | {month.solo.abbreviated(n)}
{month.integer} | {month.integer(n)}
{year.full} | {year.full(n)} | {year.abbreviated} | {year.abbreviated(n)}
{era.abbreviated} | {era.abbreviated(n)}

5. Changing the calendar

You can change the calendar that the DatePicker uses.

Change the calendar to one of the following values:
- "GregorianCalendar"
- "HijriCalendar"
- "HebrewCalendar"
- "JapaneseCalendar"
- "KoreanCalendar"
- "ThaiCalendar"
- "TaiwanCalendar"
- "UmAlQuraCalendar"
- "JulianCalendar"
```
datePicker.calendar = "ThaiCalendar";
```

6. Disabling a DatePicker

You can disable a DatePicker by setting its disabled property to true. As a result, the control is visible but dimmed and unavailable to the user.

datePicker.disabled = true;

7. Responding to the change event

You can modify behavior in your application by handling the the change event. This event is raised when the user changes a date, not when the date is changed programmatically.


datePicker.onchange = dateChangeHandler;

function dateChangeHandler(event) {
    // Insert code here.
    }

8. Changing the appearance of a DatePicker

In general, you can change the appearance of a DatePicker by using CSS styles. You can use the border-color and background-color styles to make your DatePicker stand out.

<style id="text/css">
    [class="win-datepicker"] {background-color:LightBlue; }
</style>

You can specify certain parts of a DatePicker control by using the following CSS classes:

win-datepicker
win-datepicker-date
win-datepicker-month
win-datepicker-year

For example, you can change the border color of the date dropdown:


 .win-datepicker-date
{
    border: 3px solid rgb(28, 160, 218);
}

This makes the date dropdown appear with a blue border(using the ui-light.css file) : A styled DatePicker

You can specify all three DatePicker dropdowns by using CSS attribute selector prefix syntax (^=), which finds every attribute whose name starts with the specified string:

[class^="win-datepicker"] {border:red; }

9. Showing and hiding controls

You can specify whether the day and/or the year is displayed by setting the specific dropdown's display attribute to none:

.win-datepicker-year { display:none; }

If you want to hide a dropdown for only one instance of a DatePicker, you must specify the ID of the <div> element. For example, if you want to hide the date only for the DatePicker displayed in the <div> element that has an ID of "date", do the following:

#date *.win-datepicker-date { display: none; }

10. Displaying the DatePicker dropdowns vertically

If you want to display the month, day, and year dropdowns vertically instead of horizontally, you can set the CSS attribute display on the controls. You must also set the display to block on the DIV itself.


#date {display:block;}
#date *[class^="win-datepicker"]{ display:block; }

You can conditionally display the dropdowns vertically, for example when the width of the screen falls below a specified limit. The following CSS media query specifies that the controls should be displayed vertically for all widths up to 320 pixels.

@media all and (max-width:320px) {
#date {display:block;}
*[class^="win-datepicker"] { display: block; }
}

11. Using different styles for different DatePicker instances

You can use different styles for a specific DatePicker instance by specifying the <div> element associated with that instance. For example, if you have one DatePicker in a <div> that has an ID of "start-date" and another in a <div> that has an ID of "end-date," you can set different font colors for the start date and end date DatePickers as follows:

#start-date [class^="win-datepicker"] { color:red; }
#end-date [class^="win-datepicker"] { color:blue; }

12. Using pseudo-classes to style the DatePicker

The DatePicker supports the following pseudo-classes that you can use as selectors to show certain styles when the DatePicker is in certain states.

win-datepicker:hover.The user places the cursor over the picker but does not activate it by clicking. Here the mouse is hovering over the month dropdown.
win-datepicker:active. The picker is active after the user presses the control to open the dropdown and before he or she chooses an option.
win-datepicker:focus. The picker is highlighted to accept keyboard inputs.
win-datepicker:disabled. The picker cannot accept user interaction. The disabled property of the picker must be set to true for this pseudo-class.