Using the HTML5 and jQuery UI Datepicker Popup Calendar with ASP.NET MVC - Part 4

by Rick Anderson

This tutorial will teach you the basics of how to work with editor templates, display templates, and the jQuery UI datepicker popup calendar in an ASP.NET MVC Web application.

Adding a Template for Editing Dates

In this section you'll create a template for editing dates that will be applied when ASP.NET MVC displays UI for editing model properties that are marked with the Date enumeration of the DataType attribute. The template will render only the date; time will not be displayed. In the template you'll use the jQuery UI Datepicker popup calendar to provide a way to edit dates.

To begin, open the Movie.cs file and add the DataType attribute with the Date enumeration to the ReleaseDate property, as shown in the following code:

[DataType(DataType.Date)]
public DateTime ReleaseDate { get; set; }

This code causes the ReleaseDate field to be displayed without the time in both display templates and edit templates. If your application contains a date.cshtml template in the Views\Shared\EditorTemplates folder or in the Views\Movies\EditorTemplates folder, that template will be used to render any DateTime property while editing. Otherwise the built-in ASP.NET templating system will display the property as a date.

Press CTRL+F5 to run the application. Select an edit link to verify that the input field for the release date is showing only the date.

Image of movie release date

In Solution Explorer, expand the Views folder, expand the Shared folder, and then right-click the Views\Shared\EditorTemplates folder.

Click Add, and then click View. The Add View dialog box is displayed.

In the View name box, type "Date".

Select the Create as a partial view check box. Make sure that the Use a layout or master page and Create a strongly-typed view check boxes are not selected.

Click Add. The Views\Shared\EditorTemplates\Date.cshtml template is created.

Add the following code to the Views\Shared\EditorTemplates\Date.cshtml template.

@model DateTime
Using Date Template
@Html.TextBox("", String.Format("{0:d}", Model.ToShortDateString()),
  new { @class = "datefield", type = "date"  })

The first line declares the model to be a DateTime type. Although you don't need to declare the model type in edit and display templates, it's a best practice so that you get compile-time checking of the model being passed to the view. (Another benefit is that you then get IntelliSense for the model in the view in Visual Studio.) If the model type is not declared, ASP.NET MVC considers it a dynamic type and there's no compile-time type checking. If you declare the model to be a DateTime type, it becomes strongly typed.

The second line is just literal HTML markup that displays "Using Date Template" before a date field. You'll use this line temporarily to verify that this date template is being used.

The next line is an Html.TextBox helper that renders an input field that's a text box. The third parameter for the helper uses an anonymous type to set the class for the text box to datefield and the type to date. (Because class is a reserved in C#, you need to use the @ character to escape the class attribute in the C# parser.)

The date type is an HTML5 input type that enables HTML5-aware browsers to render a HTML5 calendar control. Later on you'll add some JavaScript to hook up the jQuery datepicker to the Html.TextBox element using the datefield class.

Press CTRL+F5 to run the application. You can verify that the ReleaseDate property in the edit view is using the edit template because the template displays "Using Date Template" just before the ReleaseDate text input box, as shown in this image:

Image verifying template used

In your browser, view the source of the page. (For example, right-click the page and select View source.) The following example shows some of the markup for the page, illustrating the class and type attributes in the rendered HTML.

<input class="datefield" data-val="true" data-val-required="Date is required" 
      id="ReleaseDate" name="ReleaseDate" type="date" value="1/11/1989" />

Return to the Views\Shared\EditorTemplates\Date.cshtml template and remove the "Using Date Template" markup. Now the completed template looks like this:

@model DateTime
@Html.TextBox("", String.Format("{0:d}", Model.ToShortDateString()),
  new { @class = "datefield", type = "date" })

Adding a jQuery UI Datepicker Popup Calendar using NuGet

In this section you'll add the jQuery UI datepicker popup calendar to the date-edit template. The jQuery UI library provides support for animation, advanced effects, and customizable widgets. It's built on top of the jQuery JavaScript library. The datepicker popup calendar makes it easy and natural to enter dates using a calendar instead of entering a string. The popup calendar also limits users to legal dates — ordinary text entry for a date would let you enter something like 2/33/1999 ( February 33rd, 1999), but the jQuery UI datepicker popup calendar won't allow that.

First, you have to install the jQuery UI libraries. To do that, you'll use NuGet, which is a package manager that's included in SP1 versions of Visual Studio 2010 and Visual Web Developer.

In Visual Web Developer, from the Tools menu, select NuGet Package Manager and then select Manage NuGet Packages.

Image showing how to access Manage Nu Get Packages menu option

Note: If the Tools menu doesn't display the NuGet Package Manager command, you need to install NuGet by following the instructions on the Installing NuGet page of the NuGet website.

If you're using Visual Studio instead of Visual Web Developer, from the Tools menu, select NuGet Package Manager and then select Add Library Package Reference.

Image showing Visual Studio version to access Nu Get Package manager

In the MVCMovie - Manage NuGet Packages dialog box, click the Online tab on the left and then enter "jQuery.UI" in the search box. Select j Query UI Widgets:Datepicker, then select the Install button.

Image showing j Query U I date picker

Image 2

NuGet adds these debug versions and minified versions of jQuery UI Core and the jQuery UI date picker to your project:

  • jquery.ui.core.js
  • jquery.ui.core.min.js
  • jquery.ui.datepicker.js
  • jquery.ui.datepicker.min.js

Note: The debug versions (the files without the .min.js extension) are useful for debugging, but in a production site, you'd include only the minified versions.

To actually use the jQuery date picker, you need to create a jQuery script that will hook up the calendar widget to the edit template. In Solution Explorer, right-click the Scripts folder and select Add, then New Item, and then JScript File. Name the file DatePickerReady.js.

Add the following code to the DatePickerReady.js file:

$(function () {
    $(".datefield").datepicker(); 
});

If you're not familiar with jQuery, here's a brief explanation of what this does: the first line is the "jQuery ready" function, which is called when all the DOM elements in a page have loaded. The second line selects all DOM elements that have the class name datefield, then invokes the datepicker function for each of them. (Remember that you added the datefield class to the Views\Shared\EditorTemplates\Date.cshtml template earlier in the tutorial.)

Next, open the Views\Shared\_Layout.cshtml file. You need to add references to the following files, which are all required so that you can use the date picker:

  • Content/themes/base/jquery.ui.core.css
  • Content/themes/base/jquery.ui.datepicker.css
  • Content/themes/base/jquery.ui.theme.css
  • jquery.ui.core.min.js
  • jquery.ui.datepicker.min.js
  • DatePickerReady.js

The following example shows the actual code that you should add at the bottom of the head element in the Views\Shared\_Layout.cshtml file.

<link href="@Url.Content("~/Content/themes/base/jquery.ui.core.css")" 
        rel="stylesheet" type="text/css" />
    <link href="@Url.Content("~/Content/themes/base/jquery.ui.datepicker.css")" 
        rel="stylesheet"  type="text/css" />
    <link href="@Url.Content("~/Content/themes/base/jquery.ui.theme.css")" 
        rel="stylesheet" type="text/css" />

    <script src="@Url.Content("~/Scripts/jquery.ui.core.min.js")" 
        type="text/javascript"></script>
    <script src="@Url.Content("~/Scripts/jquery.ui.datepicker.min.js")" 
        type="text/javascript"></script>
    <script src="@Url.Content("~/Scripts/DatePickerReady.js")" 
        type="text/javascript"></script>

The complete head section is shown here:

<head>
    <meta charset="utf-8" />
    <title>@ViewBag.Title</title>
    <link href="@Url.Content("~/Content/Site.css")" 
        rel="stylesheet" type="text/css" />
    <script src="@Url.Content("~/Scripts/jquery-1.5.1.min.js")" 
        type="text/javascript"></script>
    <script src="@Url.Content("~/Scripts/modernizr-1.7.min.js")" 
        type="text/javascript"></script>

    <link href="@Url.Content("~/Content/themes/base/jquery.ui.core.css")" 
        rel="stylesheet" type="text/css" />
    <link href="@Url.Content("~/Content/themes/base/jquery.ui.datepicker.css")" 
        rel="stylesheet"  type="text/css" />
    <link href="@Url.Content("~/Content/themes/base/jquery.ui.theme.css")" 
        rel="stylesheet" type="text/css" />

    <script src="@Url.Content("~/Scripts/jquery.ui.core.min.js")" 
        type="text/javascript"></script>
    <script src="@Url.Content("~/Scripts/jquery.ui.datepicker.min.js")" 
        type="text/javascript"></script>
    <script src="@Url.Content("~/Scripts/DatePickerReady.js")" 
        type="text/javascript"></script>
</head>

The URL content helper method converts the resource path to an absolute path. You must use @URL.Content to correctly reference these resources when the application is running on IIS.

Press CTRL+F5 to run the application. Select an edit link, then put the insertion point into the ReleaseDate field. The jQuery UI popup calendar is displayed.

Image of release date field with date picker

Like most jQuery controls, the datepicker lets you customize it extensively. For information, see Visual Customization: Designing a jQuery UI theme on the jQuery UI site.

Supporting the HTML5 Date Input Control

As more browsers support HTML5, you'll want to use the native HTML5 input, such as the date input element, and not use the jQuery UI calendar. You can add logic to your application to automatically use HTML5 controls if the browser supports them. To do this, replace the contents of the DatePickerReady.js file with the following:

if (!Modernizr.inputtypes.date) {
    $(function () {
        $(".datefield").datepicker();
    });
}

The first line of this script uses Modernizr to verify that HTML5 date input is supported. If it's not supported, the jQuery UI date picker is hooked up instead. (Modernizr is an open-source JavaScript library that detects the availability of native implementations of HTML5 and CSS3. Modernizr is included in any new ASP.NET MVC projects that you create.)

After you've made this change, you can test it by using a browser that supports HTML5, such as Opera 11. Run the application using an HTML5-compatible browser and edit a movie entry. The HTML5 date control is used instead of the jQuery UI popup calendar:

Image of H T M L 5 date control

Because new versions of browsers are implementing HTML5 incrementally, a good approach for now is to add code to your website that accommodates a wide variety of HTML5 support. For example, a more robust DatePickerReady.js script is shown below that lets your site support browsers that only partially support the HTML5 date control.

if (!Modernizr.inputtypes.date) {
    $(function () {
        $("input[type='date']")
                    .datepicker()
                    .get(0)
                    .setAttribute("type", "text");
    })
}

This script selects HTML5 input elements of type date that don't fully support the HTML5 date control. For those elements, it hooks up the jQuery UI popup calendar and then changes the type attribute from date to text. By changing the type attribute from date to text, partial HTML5 date support is eliminated. An even more robust DatePickerReady.js script can be found at JSFIDDLE.

Adding Nullable Dates to the Templates

If you use one of the existing date templates and pass a null date, you'll get a run-time error. To make the date templates more robust, you'll change them to handle null values. To support nullable dates, change the code in the Views\Shared\DisplayTemplates\DateTime.cshtml to the following:

@model Nullable<DateTime>
@(Model != null ? string.Format("{0:d}", Model) : string.Empty)

The code returns an empty string when the model is null.

Change the code in the Views\Shared\EditorTemplates\Date.cshtml file to the following:

@model Nullable<DateTime>

 @{
    DateTime dt = DateTime.Now;
    if (Model != null)
    {
       dt  = (System.DateTime) Model;
   
    }
    @Html.TextBox("", String.Format("{0:d}", dt.ToShortDateString()), new { @class = "datefield", type = "date"  })
}

When this code runs, if the model is not null, the model's DateTime value is used. If the model is null, the current date is used instead.

Wrapup

This tutorial has covered the basics of ASP.NET templated helpers and shows you how to use the jQuery UI datepicker popup calendar in an ASP.NET MVC application. For more information, try these resources:

  • For information about jQuery UI, see jQuery UI.
  • For information about how to localize the datepicker control, see UI/Datepicker/Localization.
  • For more information about the ASP.NET MVC templates, see Brad Wilson's blog series on ASP.NET MVC 2 Templates. Although the series was written for ASP.NET MVC 2, the material still applies for the current version of ASP.NET MVC.