Calendar Tag Helper Overview
The Calendar tag helper helps you configure the Kendo UI Calendar widget in ASP.NET Core applications.
Basic Usage
The following example demonstrates how to define the Calendar by using the Calendar tag helper.
Example
<kendo-calendar name="calendar" >
</kendo-calendar>
@(Html.Kendo().Calendar()
.Name("calendar"))
Configuration
The Calendar provides configuration options that can be set during initialization.
The available properties are:
- Selected date
- Minimum and/or maximum date
- Start view
- Week numbers
- Selection
- Navigation depth—that is, the option to define the last view to which the user can navigate.
- Day template
- Footer template
Selected, Minimum, and Maximum Dates
The following example demonstrates how to create a Calendar with a selected date and a defined minimum and maximum dates. As a result, the Calendar does not navigate to a date that is earlier than the specified minimum date and also restricts the navigation to the maximum date you specified.
Example
<kendo-calendar name="calendar"
value="DateTime.Now"
min="new DateTime(1950,1,2)"
max="new DateTime(2049,12,31)">
</kendo-calendar>
@(Html.Kendo().Calendar()
.Name("calendar")
.Value(DateTime.Now)
.Min(new DateTime(1950, 1, 2))
.Max(new DateTime(2049, 12, 31)))
Start View and Navigation Depth
To define the first rendered view, use the start option. To control the navigation depth, set the depth option.
The following views are predefined:
-
month—Shows the days of the month. -
year—Shows the months of the year. -
decade—Shows the years of the decade. -
century—Shows the decades of the century.
Day Templates
The Calendar enables you to customize the rendered day for the month view.
The following example demonstrates how to create a Calendar by using a custom template.
Example
<kendo-calendar name="calendar">
<month content="<div class='custom'><#=data.value#></div>"/>
</kendo-calendar>
@(Html.Kendo().Calendar()
.Name("calendar")
.MonthTemplate(x=> x.Content("<div class='custom'><#=data.value#></div>")))
The template wraps the value in a <div> HTML element. The structure of the data object that is passed to the template function:
data = {
date: date, // Date object corresponding to the current cell
title: kendo.toString(date, "D"),
value: date.getDate(),
dateString: "2011/0/1" // formatted date using yyyy/MM/dd format and month is zero-based
};
Week Numbers
You can configure the Calendar to display the week number and also use the week number template to customize the cells in the Week column.
Rendering of Week Numbers
The weekNumber option enables the Calendar to display the week number on an annual base to the left side of month view and as a separate column.
Example
<kendo-calendar week-number="true" name="calendar">
</kendo-calendar>
@(Html.Kendo().Calendar()
.Name("calendar")
.WeekNumber(true)))
Customizing Week Column Cells
The week-number template intends to customize the cells in the Week column. By default, the widget renders the calculated week of the year.
The available properties in the data object are:
-
currentDate—Returns the first date of the current week. -
weekNumber—The calculated week number.
You can use these properties in the template to make additional calculations.
Example
<kendo-calendar week-number="true" name="calendar">
<month week-number="<i>#= data.weekNumber #</i>" />
</kendo-calendar>
@(Html.Kendo().Calendar()
.Name("calendar")
.WeekNumber()
.MonthTemplate(x=> x.WeekNumber("<i>#= data.weekNumber #</i>"))
)
Selection
The Calendar enables the user to make a single, multiple, and range date selections, as well as week selections. For a runnable example on multiple selection, refer to this demo.
Single Date Selection
By default, the user can select a single date from the Calendar by using the mouse or the keyboard and you do not need to make additional configuration to enable the single date selection.
Multiple Date Selection
As of the Kendo UI 2017 R3 release, the Calendar allows you to implement the multiple date selection by using the selectable configuration property.
To perform the multiple date selection, the user can also use the keyboard:
-
Ctrl+ mouse click on specific date marks the date as selected and other previously selected dates remain selected as well. - The selection of a date from a specific view without utilizing the
Ctrlkey, deselects all previously selected dates—including the previously selected dates from other views or months, and selects the date of the clicked cell. - The selection of a date that is already selected while holding the
Ctrlkey removes the date from the selection.
Example
<kendo-calendar selectable="multiple" name="calendar">
</kendo-calendar>
@(Html.Kendo().Calendar()
.Name("calendar")
.Selectable("multiple")
)
Range Date Selection
The Calendar enables the range date selection over the keyboard. The usage of the Shift key allows the user to select a range of dates in the same month or across different months:
- To select all dates between the most recently selected one (with
Spaceor mouse click) and the clicked cell, pressShiftand click with the mouse. - If no previous selection was made,
Shiftand a mouse click select all dates from the beginning to the clicked cell.
Week Selection
When the user clicks on a specific week number, the Calendar selects the entire week. The week selection functionality is a special case of range selection which starts from the first day of the week and selects all dates to the end of the week.
Disabling Dates
The Calendar allows you to disable certain days which are not intended to be selected by the end user such as weekends, national holidays, and others.
To disable a date, either:
- Set an array, or
- Add a function.
Setting an Array
When you set an array, list the days that need to be disabled by using the first letters from their names in English.
Example
<kendo-calendar disable-dates="new DateTime[] { DateTime.Now.AddDays(2), DateTime.Now.AddDays(2) }" value="DateTime.Now" name="calendar">
</kendo-calendar>
@(Html.Kendo().Calendar()
.Name("calendar")
.Value(DateTime.Now)
.DisableDates(new[] {DayOfWeek.Monday })
)
Adding a Function
When you add a function, determine its return value as true for the date that is disabled.
Example
<div class="demo-section k-content" style="text-align: center;">
<kendo-calendar disable-dates-handler="disabledDatesHandler" value="DateTime.Now" name="calendar">
</kendo-calendar>
</div>
<script>
function disabledDatesHandler(date) {
var disabled = [13, 14, 20, 21];
if (date && disabled.indexOf(date.getDate()) > -1) {
return true;
} else {
return false;
}
}
</script>
Keyboard Navigation
The keyboard navigation of the Calendar works by listening to the key-down events on the wrapper element of the widget. The logic assumes that everything the user does is in accordance with the currently focused date cell and not the focused element of the browser.
Depending on selection type (single or multiple), the Calendar behaves differently in terms of selecting and navigating with the keyboard. When the user applies the multiple date selection, the Calendar demonstrates the following keyboard navigation behavior:
- The focusing or selection of a date from another month does not navigate to the corresponding month. The user is able to continue the selection of dates from the current view.
- The pressing of
SpaceorEnteron a specific date makes a single selection by deselecting all other selected dates. - The pressing of
SpaceorEnteron a specific date while the user is holding theCtrlkey adds the date to the current selection. If the date is already selected, it is removed from the selection. - The pressing of
Shift+EnterorSpaceperforms a range selection. It selects all dates between the most recently selected date (withSpaceorEnteror a mouse click) and the date that holds the focused cell. - The pressing of
Shift+Up ArroworDown Arrowextends the selection up or down one row in the month view respectively. - The pressing of
Shift+Right ArroworLeft Arrowadds the next or previous date to the current selection respectively.
For a runnable example on performing date selection over the keyboard, refer to this demo.