Kendo DatePicker Wrapper for ASP.NET MVC

Overview:

This is the fourth post in a series on Kendo UI wrappers for ASP.NET MVC. In this post we will look at one more wrapper named DatePicker. Before we get on with DatePicker Kendo wrapper, if you are new and want to learn more about Kendo Wrappers for ASP.NET MVC, I suggest you take a look at “Jumpstarting Development with Kendo UI for ASP.NET MVC” by Abhishek Kant. The jumpstarting blog post will give you the basics on how to get started with Kendo for ASP.NET MVC. Here is the post which has links to all other blog post of the series.

What is DatePicker control?

DatePicker is a control which allows end user to select a date from a calendar or by inputting the data directly. The DatePicker control supports customizing the month view by providing a custom template. The Minimum date, Maximum date and the view to start out with are all configurable through options.

image

Instantiating a DatePicker:

to instantiate a DatePicker control on the page, we make use of the DatePicker builder available in as part of the Kendo wrapper helpers. Take a look at the below code to see how DatePicker is instantiated:

@( Html.Kendo().DatePicker().Name("kdatepicker") )

Here is the output of the above code:

image

As you can see we just instantiated the DatePicker control on the page. The control is made up of the textbox for manual input and a button (having calendar icon) which when clicked will bring up a calendar so that user can select any date.

Setting default value at instantiation:

In the previous section we saw how to instantiate a DatePicker control. But when it was rendered we did not see any default value i.e. a default date being displayed in the textbox. Well, that is because we never told the control what its default value was. DatePicker control exposes a method called Value() which can be used to set the default value. Here is a code to set the default value of the control to current day:

@(Html.Kendo().DatePicker().Name("kdatepicker")
      .Value(DateTime.Today)
)

Here is the output as a result of setting the default value to the control:

image

Formatting selected value:

We saw how to set the default value of the date picker control. The default format in which the date value is shown is MM/DD/YYYY. If you want to customize the format, the control provides the option to use the Format() method and provide any valid date time format that we are familiar with. So here is the code to set the format as “<Day Name>, <Month Name> <Date>, <Year>”:

@(Html.Kendo().DatePicker().Name("kdatepicker")
      .Value(DateTime.Today)
      .Format("dddd, MMMM dd, yyyy")
      .HtmlAttributes(new { style = "width:230px"})
)

I have used the Format() method and passed in a format “dddd, MMMM dd, yyyy” and below is the output of that code:

image

Putting constraints for selection:

When using date pickers in a real world applications, one of the common scenario is to restrict the dates a user can select. Usually we will have a minimum date and maximum date range and we would like the calendar to show only those dates and user can select only from those dates. DatePicker control provides Min() and Max() method which accept a DateTime value and use these two settings to restrict the values. Here is the code to use the Min & Max methods. I am setting the minimum date to be today and maximum date to be 4 days from today:

@(Html.Kendo().DatePicker().Name("kdatepicker")
      .Value(DateTime.Today)
      .Format("dddd, MMMM dd, yyyy")
      .Min(DateTime.Today)
      .Max(DateTime.Today.AddDays(4))
      .HtmlAttributes(new { style = "width:230px"})
)

Here is the output of the above code:

image

Customizing the Calendar Views:

So far we have seen that when the calendar is used for selecting a date, by default it shows the month view i.e. it shows current month and the days in that month. DatePicker control also has the provision to customize the calendar view and we can do that by using the Start() method. The Start() method accepts a enum of type CalendarView. CalendarView has options Century, Decade, Month and Year. You just set what view you would like to see and the calendar will show that particular view every time users open the calendar.  Here is a code to set the start view of the calendar to Century:

@(Html.Kendo().DatePicker().Name("kdatepicker")
      .Value(DateTime.Today)
      .Format("dddd, MMMM dd, yyyy")
      .Start(CalendarView.Century)
      .HtmlAttributes(new { style = "width:230px"}) )

Here is the output for the same:

image

Here is an example of all the calendar views:

image

Customizing cell rendering:

Imagine a scenario where you want to customize how a particular day needs to be rendered on the calendar. For e.g. November 9 is my birthday. So whenever Nov 9 is rendered I want to be reminded that its my birthday and I want a cake icon to be shown on that day. For such a scenario, DatePicker control has the provision to customize each cell rendering. This is done by passing a template to a method named MonthTemplate(). You can pass any valid kendo template string to this method. Here is the code to show a birthday cake on Nov 9 of every year:

@(Html.Kendo().DatePicker().Name("kdatepicker")
.Value(DateTime.Today)
.Format("dddd, MMMM dd, yyyy")
.HtmlAttributes(new { style = "width:230px"})
.MonthTemplate(" # if (data.value == 9 && data.date.getMonth() == 10) { # " +
"<div class=birthday /> " +
"# } #  " +
"#= data.value #")
)

What I have done is to pass a template string. If you look at the template itself, I am just checking if the current rendered date is 9 and current rendering month is November (remember JavaScript month array is zero index based, so Nov = 10) and if yes I am showing a div with class birthday. The stylesheet for birthday just puts a cake image. We show the date value irrespective of the check we do. Here is the output of the above code:

image

Customizing the footer:

When the calendar is open, it usually shows the current day in “<Day Name>, <Month Name> <Date>, <Year>” format at the bottom. This is known as the footer. This footer can be customized by providing a custom template. Here is the code to customize the footer:

@(Html.Kendo().DatePicker().Name("kdatepicker")
.Value(DateTime.Today)
.Format("dddd, MMMM dd, yyyy")
.HtmlAttributes(new { style = "width:230px"})
.Footer("Today - #= kendo.toString(data,'ddd, MMM dd, yyyy') # ")
)

Here is the output of the same:

image

Summary:

In this post, we looked at one more Kendo Wrapper named DatePicker. We looked at how easy it is to instantiate the control. set a default value, formatting the selected value, restricting the dates that can be picked, customizing the calendar view, customizing the cell rendering and finally how to customize the footer of the calendar. Hope this gives you a jumpstart at developing with Kendo DatePicker wrapper for ASP.NET MVC.

Till next time – Happy Coding!

Kendo Calendar Wrapper for ASP.NET MVC

Overview:

In this post we will learn about one more wrapper from Kendo UI library called Calendar. If you are starting new on Kendo UI, make sure to go through the blog post – Jump starting Development with Kendo UI for ASP.NET MVC. We will look at the usage of the Calendar widget and how to program the Calendar widget. If you are looking for the index post on this getting started series, click here.

To follow this blog post, just create a “C# Kendo UI for MVC Web Application” project type and work along.

What is Calendar Widget:

The Calendar Widget renders a graphical calendar that supports navigation and selection. It supports custom templates for its “month” view, configurable options for a minimum and maximum date, start view and the depth of the navigation.

image

Instantiating a Calendar:

To instantiate a Calendar widget on any page, we just make use of the Calendar builder available within the Kendo helper. Here is the code snippet to instantiate a  Calendar:

   1: @(Html.Kendo().Calendar()

   2:               .Name("kcalendar")

   3: )

Note that the “Name” is mandatory setting. This defines the ID of the control on the client side. So here is the output of the code we wrote:

image

That’s it – with just one line of code we have a Calendar on our page. Next lets see how we can control the Calendar View.

Calendar View Settings:

Be default if nothing is said about the view we need to see on the Calendar, it is going to use Month view i.e. the current month is shown in the calendar. The Calendar widget has the following view options to choose from:

  • Century – When selected, Calendar will show decades of the current century
  • Decade – When selected, Calendar will show years of the the current decade
  • Month – When selected, Calendar will show days of the current month
  • Year – When selected, Calendar will show months of the current year

The way we set the view is through a method called Start(). The different view settings are available as a CalendarView enum. Here is the code snippet to set the view of the calendar:

   1: @(Html.Kendo().Calendar()

   2:               .Name("kcalendarCentury")

   3:               .Start(CalendarView.Century)

   4:             )

Here is the output of the above code:

image

Setting Calendar Value:

So far we have been able to instantiate a calendar on the page. But if you notice clearly the current date is not highlighted by default. The current date is displayed at the footer of the calendar but the day is not highlighted. That is because, calendar has a property called Value() and to have a date highlighted this property needs to provided with a DateTime instance. It can be current day or any other day. Here is the code snippet to set the value of the calendar:

   1: @(Html.Kendo().Calendar()

   2:               .Name("kcalendarvalue")

   3:               .Value(DateTime.Today)

   4:  )

All we are doing is setting the Value of the calenda to DateTime.Today instance. Here is output of that code:
image

Setting Calendar Value:
Many a times when using calendar we will have scenarios where we need to restrict the dates that the user can select. For e.g. lets assume that we want to user to select the dates between 19 Nov and 23 Nov only. That means the minimum date that can be selected is 19 Nov and maximum date that can be selected is 23 Nov. Well to achieve this scenario, the calendar provides Min() and Max() property and both of this method accept either a string representing a date  or an instance of DateTime. Here is the code snippet for setting Min & Max property:
   1: @(Html.Kendo().Calendar()

   2:               .Name("kcalendarrestriction")

   3:               .Min("2012/11/19")

   4:               .Max("2012/11/23")

   5:  )

And here is the output of the changes we made:
image
As you can see it does not show the dates outside of the allowed Min and Max date settings.
Accessing Calendar from client side:
You may have a scenario where you want to get hold of the calendar widget from JavaScript. This can be achieved by using the jquery.data() method. Assume that we had named our calendar as “kcalendar”, here is the code snippet to access that from JavaScript:
   1: var calendar = $("#kcalendar").data("kendoCalendar");

As you can see, we just use jquery’s data() syntax to get the Kendo Calendar object. The Kendo controls all have very rich client side API that you can work with. For e.g. if we have to set the value of the calendar from client side you can use the value() method on the control. Here is the code snippet for the same:
   1: var calendar = $("#kcalendar").data("kendoCalendar");

   2: calendar.value(new Date(2012, 0, 1));

Configuring client side events:
Kendo Calendar exposes two client side events which can be hooked into while instantiating the control. The event exposed are:
  • Change – occurs when the value is changed
  • Navigate – occurs when any navigation is performed by the user i.e. month change, year change etc.
When we hook into the events exposed, we just configure the JavaScript function which will handle the event on the client side. Here is the code snippet to handle the value change event of the calendar:
   1: @(Html.Kendo().Calendar()

   2:               .Name("kcalendarevents")

   3:               .Events(evnt => evnt.Change("onValueChange"))

   4:  )

   5: <script>

   6:     function onValueChange(e)

   7:     {

   8:         var kcal = $("#kcalendarevents").data("kendoCalendar");

   9:         alert(kcal.value());

  10:     }

  11: </script>

Similarly you can handle the Navigate event also.
Summary:
Kendo Calendar is yet another wrapper available in the Kendo UI library – which lets you create a graphical calendar on a web page. We saw how simple it is to instantiate on any page. We also saw some of the properties supported by the control. We also saw how to work with the control from client side i.e. from JavaScript. Hope this provides you with a kind of quick start to work with Kendo UI Wrappers. Stay tuned for many more of these posts on Kendo UI Wrapper usage.
Till next time – Happy coding!