This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!
Introduction to the Calendar Web Control
The Calendar Web control can serve these purposes:
- Display and select dates The control displays a calendar that users can navigate in to see any date in any year. The current date is highlighted. Optionally, users can move to arbitrary dates by clicking a day and moving from month to month. The calendar can be configured to allow users to select multiple dates, either an entire week or an entire month.
Typical uses are to graphically display the current date on a daily news Web page, or to allow users to select dates in scheduling applications such as ordering airline reservations, concert tickets, and so on.
- Display appointment or other information in a calendar grid The Calendar Web control can display day-specific details for individual days, such as a to-do list, a schedule of events, or similar information. This feature allows you to display day information from a database.
The Calendar Web control is based around the NGWS DateTime object, and therefore supports the full range of dates allowed by that object. Effectively, you can display virtually any date between the years 0 and 9999 A.D.
The Calendar control is rendered as an HTML table when the Web Forms page runs. Therefore, a number of the control's properties pertain to various aspects of table formatting. A few of these properties are not fully supported in some older browsers, so some formatting features will not be available.
Developing with the Calendar Web Control
The following sections contain details about how the Calendar Web control works and an overview of tasks you can accomplish with it.
Displaying and Selecting Dates
The Calendar Web control displays a month of dates at a time, with a total of six weeks appearing at once. Within the control, there are several types of dates that you can work with:
- Today's date By default, the current date on the server. However, you can adjust it so that the date appears correctly in a different locale.
- Visible date This date determines what month appears in the calendar. The user can move from month to month on the calendar, thereby changing the visible date without affecting today's date. You can navigate between months by setting this date programmatically.
- Selected date or dates This is the date or date range that the user chooses in the control. In the control, the user can choose a single day, week, or month, but can only select contiguous dates. You can also programmatically set the selected dates; in that case, you can set non-contiguous selected dates.
Enabling Date Selection
By default, the calendar allows users to click an individual date to select it. If you are using the control as a read-only calendar, you can disable all date selection.
If day selection is enabled, each day of the calendar contains a LinkButton Web control that raises an event when clicked. If you enable week or month selection, a column of links is added to the left side of the calendar to enable the user to specify what week to select.
Customizing the Calendar's Appearance
You can set calendar properties to change the colors, size, text, and other visual features of the calendar. There are a number of ways to do this:
- Setting properties You can set properties to specify whether the calendar shows grid lines, change what day is displayed as the first day of the week, and change the appearance of the month and day names.
- Setting extended style properties You can use properties derived from the Style object to set the appearance of particular elements in the calendar, such as today's date, the title bar containing the month and navigation links, and so on. These style properties are supported in browsers that can use cascading style sheets; a reduced set of appearance styles is supported for earlier browsers.
- Customizing the rendering of individual days As the control renders individual days, it raises an event you can handle to modify the stream being rendered to the browser. This is useful not just for changing the appearance of days, but for including custom content on each day as well.
Capturing User Interaction with the Calendar Web Control
The Calendar Web control raises an event when the user selects an individual date or range of dates, or when navigating to a new month. By creating handlers for these events, you can determine what day or dates the user has selected and respond appropriately.
By creating custom day output, you can include arbitrary HTML in the calendar, including other controls.
Displaying Information from a Database in the Calendar Control
A common scenario is to display information from a database in the calendar. For example, an events calendar is often based out of information kept in a database.
The Calendar control does not directly support databinding — that is, you do not bind the calendar as a whole to a data source. Instead, you create a handler for the control's OnDayRender event, which is raised as each day in the current calendar month (view) is being rendered. In the handler for this event, you can extract information from a data source and add it to the stream being sent to the browser.
See Also
Using the Calendar Web Control