Instructor-led online courses in ASP.NET Core, ASP.NET MVC, and ASP.NET Design Patterns. Conducted by Bipin Joshi on weekends. More details are available here.

Create Strongly Typed Custom HTML Helper for Picking Dates

Recently a beginner asked me as to how a strongly typed HTML helper
can be created. Although the process is relatively simple you need to keep in
mind a certain steps. In this short article I will explain how a custom HTML
helper can be created to render an HTML5 date picker input field. I will explain
unbound as well as model bound versions for better clarity.

ASP.NET MVC offers TextBox() and TextBoxFor() helper to render a textbox that
is unbound and model bound respectively. You can use the same helpers to render
an HTML5 date picker by supplying an anonymous object as shown below:

As you can see from the above code, you can override the default input type
from text to date by supplying the anonymous object. This works well in many
cases but at times you may prefer creating a custom HTML helper that saves that
extra step of overriding input type. In nutshell you may want to write something
like:

@Html.DatePicker("birthdate")
@Html.DatePickerFor(m=>m.BirthDate)

You can achieve this by creating a custom HTML helper. To illustrate how this
can be accomplished, let's develop unbound as well as model bound helper that is
intended to display date fields.

Model

Begin by creating a new ASP.NET MVC application in Visual Studio. Add an
Entity Framework data model for the Employees table of Northiwnd database. The
Employee entity class will look like this:

We will use the BirthDate property of the Employee class and display it in
the date picker custom helper.

Now, add a folder named CustomHelpers and add a class to it -
DatePickerHelper.cs

The DatePicker class is marked to be static and all its methods are static.
You might have already guessed they are extension methods of HtmlHelper class.
In order to create a custom HTML helper you need to write it as an extension
method of inbuilt HtmlHelper class. The HtmlHelper class resides in
System.Web.Mvc namespace. All the extension methods of DatePicker class will
return MvcHtmlString - a class that wraps all the HTML markup to be rendered in
the browser as a part of the extension method.

The above code shows two overloads of DatePicker() method. The first overload
accepts helper and name parameters whereas the second overload accepts helper,
name and value parameters. The helper parameter indicates that this method is
extending HtmlHelper class. The name parameter indicates the name of the date
picker control in the final HTML markup. The value parameter indicates the
default value of the date picker.

Inside, the methods use TagBuilder to construct the <input> element needed to
display the date picker. Notice that the name and as well as id attributes are
set to the name you specify. The type attribute is set to date. In the second
overload even the value attribute is set to the value parameter of the extension
method. HTML5 date picker requires date value in ISO date format (yyyy-MM-dddd)
and that's why the supplied date is formatted as shown.

An MvcHtmlString is constructed using the ToString() method of the TagBuilder
class. Since the input tag is self closing (<input ... />) TagRenderMode is
specified as SelfClosing. The MvcHtmlString instance is then returned from the
methods.

Strongly typed or model bound DatePicker helper

So far so good. Now let's develop the model bound version. This will require
some more steps and the code is slightly complex than before.

Add another method to the DatePicker class with the following signature:

The DatePickerFor() method is a generic method that allows you to specify
type of model (TModel) and its property to be bound (TProperty). It takes two
parameters helper and expression. The helper parameter is similar to the earlier
versions but also specifies TModel. The Expression parameter indicates the
property of model to be bound. I won't go into the details of LINQ and Lambda
expressions here. It is suffice to say that the expression parameter represents
the model property to be bound with the date picker field.

The first line determines the name of the date picker. This is done using
GetExpressionText() method of ExpressionHelper class. You pass the lambda
expression to this method as a parameter and it will return its string
representation. For example, if you pass m=>m.BirthDate then datePickerName
would be BirthDate.

The next line determines the fully qualified name of the date picker. This is
done to cover scenarios where the date picker is nested or is placed in partial
pages. Finally, client side ID of the date picker is determined using
CreateSanitizedId() method of TagBuilder class.

The above code grabs the value of the date picker. This value comes from the
specified model property. ModelMetadata object basically represents metadata
about the model properties and in this case you are retrieving one based on the
expression. The second line examines the metadata.Model property to decide
whether property value is null or not. If it is null, current date-time is
assigned to datePickerValue variable, otherwise value of Model property is
assigned to datePickerValue.

Now, further add the following code that forms the <input> tag for the date
picker field:

This code should be familiar to you by now. It uses a TagBuilder object and
adds name, id, type and value attributes. As before value attribute is formatted
as yyyy-MM-dd.

The code you wrote so far takes care of rendering a date field that is data
bound. However, in real-world cases the field under consideration might be
validated using client side script and data annotations. To take care of this
possibility you need to add the following code:

The GetUnobtrusiveValidationAttributes() method returns a Dictionary that
contains all the client side custom data attributes (data-*) required for the
proper functioning of unobtrusive JavaScript based validation. A foreach loop
iterates through this Dictionary and adds those attributes to the TagBuilder
object under consideration.

Finally, MvcHtmlString is obtained from the TagBuilder as shown below:

Enabling Unobtrusive JavaScript Validations

In the previous sections you took precaution to emit attributes necessary for
unobtrusive validations. So, let's enable them so that we can test our helper
accordingly. Add a class - EmployeeMetadata and write the following code into
it:

The EmployeeMetadata class defines BirthDate property. It also decorates the
property with [Required] attribute. Then EmployeeMetadata is attached with the
Employee model class as its metadata class. This is done using the partial
Employee class.

The following figure shows how the model bound date picker is displayed in
the browser and how the unobtrusive validations work in case BirthDate is kept
empty.

You will find that if you comment out the foreach loop from the DatePickerFor()
method then client side unobtrusive validations stop working.

That's it! Keep coding !!

Bipin Joshi is a software consultant, trainer, author and spiritual yoga mentor having 23+ years of experience in software development. He teaches online training courses in ASP.NET Core, ASP.NET MVC, and Design Patterns to individuals and small groups. He is a published author and has authored or co-authored books for Apress and Wrox press. Having embraced the Yoga way of life he also teaches Ajapa Yoga to interested individuals. To know more about him click here.