Introduction
BetterCalendar is a custom control derived from System.Web.UI.WebControls.Calendar. It is designed to correct some problems with the Calendar control and add some additional functionality.
Background
The Calendar control is quite useful but it has a few bugs and drawbacks:
-
It's impossible to set a calendar's appearance using only style sheets (i.e., assigning class names to the CssClass property on the various calendar style elements). This is because the control embeds inline style attributes for many elements when style properties are defaulted.
For example, the HTML for a day cell might look like:
<td class="calendarDay" align="Center" style="width:12%;">
<a href="javascript:__doPostBack('Calendar1','1566')"
style="color:Black">15</a></td>
Here, the color setting of style attribute will override any color setting in the calendarDay class.
-
While you can define different styles for a day based on certain conditions - via the DayStyle, WeekendDayStyle, OtherMonthDayStyle, TodayDayStyle and SelectedDayStyle properties - only one style class is assigned even when more than one may apply.
In other words, if today's date falls on a week end and it is selected on the control, the SelectedDayStyle style takes precedence:
<td class="selectedDay_style" ... >
Since an HTML element may be assigned multiple class names in its class attribute, it's possible to include all applicable style classes like this:
<td class="day_style weekendDay_style todayDay_style selectedDay_style" ... >
This would give you full control over how it appeared via a style sheet.
-
Using the DayRender event, you can control which days
are selectable and which are not. However, when week or month selectors
are active on the control, all days in the given week or month are
included in the selection, regardless of whether they are individually
selectable or not. You could use the SelectionChanged event to manually remove such dates, but that's doing the same work twice.
-
Lastly, there is no limit on the next and previous month navigation
controls. You can pro grammatically prevent viewing of months outside
some range via the VisibleMonthChanged event, but the next and previous links are always rendered on the control.
The BetterCalendar control addresses these issues.
Using the code
The control is packaged in a class library with the namespace BrainJar.Web.UI.WebControls which contains only the one class, BetterCalendar.
Within a Visual Studio web project, you can simply add a reference to the BrainJar.Web.UI.WebControls.dll file. You can then edit your web form in HTML view and add the appropriate @ Register directive and tags. A typical example is shown below (note the inclusion of an external style sheet).
<%@ Page language="c#" Codebehind="WebForm2.aspx.cs" AutoEventWireup="false"
Inherits="Demo.WebForm2" %>
<%@ Register TagPrefix="BrainJar" Namespace="BrainJar.Web.UI.WebControls"
Assembly="BrainJar.Web.UI.WebControls"%>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" >
<HTML>
<HEAD>
<title>WebForm1</title>
<meta name="GENERATOR" Content="Microsoft Visual Studio 7.0">
<meta name="CODE_LANGUAGE" Content="C#">
<meta name=vs_defaultClientScript content="JavaScript">
<meta name=vs_targetSchema
content="http://schemas.microsoft.com/intellisense/ie5">
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<link href="Styles.css" type="text/css" rel="stylesheet">
</HEAD>
<body>
<form id="WebForm1" method="post" runat="server">
<h1>BetterCalendar Control Demo</h1>
<BrainJar:BetterCalendar id="BetterCalendar1" runat="server">
<DayStyle CssClass="calendarDay"></DayStyle>
<DayHeaderStyle CssClass="calendarDayHeader"></DayHeaderStyle>
<NextPrevStyle CssClass="calendarNextPrev"></NextPrevStyle>
<OtherMonthDayStyle CssClass="calendarOtherMonthDay">
</OtherMonthDayStyle>
<SelectedDayStyle CssClass="calendarSelectedDay"></SelectedDayStyle>
<SelectorStyle CssClass="calendarSelector"></SelectorStyle>
<TitleStyle CssClass="calendarTitle"></TitleStyle>
<TodayDayStyle CssClass="calendarTodayDay"></TodayDayStyle>
<WeekendDayStyle CssClass="calendarWeekendDay"></WeekendDayStyle>
</BrainJar:BetterCalendar>
</form>
</body>
</HTML>
You can also add the control to the toolbox in the usual way (in
Design mode, right-click on the toolbox, select "Customize Toolbox...",
select the ".NET Framework Components" tab, press the "Browse" button
and select the BrainJar.Web.UI.WebControls.dll file).
Since BetterCalendar is derived from the Calendar
control, it inherits all of that control's properties, methods and
events. In addition to those, it defines four new properties:
SelectAllInRange (Boolean)
For use with week and month selectors (see the Calendar.SelectionMode property documentation). If set to true, all dates in a given week or month are selected. When set to false, only dates that are individually selectable are included. The default is false. See the demo project for an example of how this affects the control.
ShowLinkTitles (Boolean)
Setting this property to true adds title
attributes to the links rendered on the control with text describing
their function. For example, the previous month navigation link will be
given a title like "View December, 2003."
Using titles can improve the accessibility of your web form. Many browsers render title information in a tool tip, but specialized browsers may render it in speech or Braille.
Warning: Although day and month names and dates are generated
according to the current culture, the remaining title text is in
English.
MaxVisibleDate (DateTime)
Sets an upper limit on the month the user can navigate to using the
next month navigation link. When the currently viewed month is the same
as MaxVisibleDate, the next month navigation link is omitted from the display.
MinVisibleDate (DateTime)
Sets a lower limit on the month the user can navigate to using the
next month navigation link. When the currently viewed month is the same
as MinVisibleDate, the previous month navigation link is omitted from the display.
Note that both MixVisibleDate and MaxVisibleDate default to System.DateTime.MinValue, which is interpreted to mean that no limit is set.
Design-Time Support
BetterCalendar includes metadata for design-time
support in Visual Studio .NET, so the new properties will appear in the
Properties window when editing an instance of the control in Design
view.
While it's not necessary in order to use the control, the source code includes a file named BrainJar.xsd that can be used to remove those embarrassing red squiggly lines when editing the control in HTML view.
To use the schema, copy BrainJar.xsd to your vs_install_directory\Common7\Packages\schemas\xml directory (where vs_install_directory is the directory Visual Studio .NET was installed in, usually C:\Program Files\Microsoft Visual Studio .NET). Then add a declaration for it in the BODY tag of your web form:
<body xmlns:BrainJar="urn:http://schemas.brainjar.com/AspNet/WebControls">
To add Intellisense support for the control when editing your code-behind, you can copy the BrainJar.Web.UI.WebControls.xml file from the project source (in the \debug directory) to your project's \bin directory.
The Demo Project
Several features of the BetterCalendar control can be seen in the demo project. The project contains a single web form which has both a regular Calendar control and a BetterCalendar control.
Both calendars are styled using only CSS classes defined in an external style sheet (the Styles.css
file). Different styles are used for weekend days, days outside the
current month, selected days, etc. You can immediately see how the Calendar control fails to deal with style classes properly.
In the code-behind, the BetterCalendar control is initialized to set MinVisibleDate and MaxVisibleDate to 90 days before and after the current date, respectively.
private void Page_Load(object sender, System.EventArgs e)
{
if (!this.IsPostBack)
{
this.BetterCalendar1.MinVisibleDate = DateTime.Today.AddDays(-90);
this.BetterCalendar1.MaxVisibleDate = DateTime.Today.AddDays(+90);
}
}
If you page through the months on the BetterCalendar
control, you'll note that the next or previous month navigation link
will disappear when you reach the corresponding date limit.
For both calendars, a DayRender event handler is set up. Within it, we compare the day's date to this same date range. Days outside the range have their IsSelectable property set to false.
private void Calendar_DayRender(object sender,
System.Web.UI.WebControls.DayRenderEventArgs e)
{
if ((this.BetterCalendar1.MinVisibleDate != DateTime.MinValue &&
e.Day.Date < this.BetterCalendar1.MinVisibleDate) ||
(this.BetterCalendar1.MaxVisibleDate != DateTime.MinValue &&
e.Day.Date > this.BetterCalendar1.MaxVisibleDate))
e.Day.IsSelectable = false;
}
By navigating to the month at either end of the date range, can see
that both calendars contain the same non-selectable days. Now, try
clicking on the month selector (the ">>" link next to the days
header). The Calendar control selects every day in the month, even the ones that we explicitly marked as non-selectable in the DayRender event handler.
If you select the same month on the BetterCalendar
control however, you'll see that the dates marked as non-selectable are
excluded. The same applies to weeks that contain non-selectable dates.
If you'd prefer to have BetterCalender behave like Calendar on week and month selections, you can just set the control's SelectAllInRange property to true.
Points of Interest
Control Rendering
Most of the code for BetterCalendar is dedicated to the overridden Render method. The Calendar control produces a fair amount of HTML and there are several display options like NextPrevFormat, NextMonthText, PrevMonthText, ShowTitle, TitleFormat, ShowDaysHeader, FirstDayOfWeek, etc., to account for. So, some of the work is broken out into separate functions for the sake of readability.
For the most part, the control is built using existing controls from System.Web.UI.WebControls
rather than by writing raw HTML. It's much easier to use the properties
and methods inherent to those controls for assigning attributes and
applying styles than it is to manually write them as HTML.
Value Checking (or not)
No value checking is done when the MinVisibleDate, MaxVisibleDate or VisibleDate properties are set. It would be fairly easy to add code to throw a System.ArgumentOutOfRangeException if any one of those properties were assigned a value that makes VisibleDate less than MinVisibleDate or greater than MaxVisibleDate.
However, even if VisibleDate is out of the implied
range, it causes no problems within the control. So rather than throw
exceptions, it's left to the application programmer to ensure that
those properties are consistent. This allows you some flexibility as
you don't need to worry about setting these properties in any
particular order.
Post Back Events
The Calendar control uses post back links to handle the
next and previous month navigation and date selection. When viewing a
calendar in a browser, you can hover over a date link and see something
like:
javascript:__doPostBack('Calendar1','1646')
for the URI. 'Calendar1' is the control ID and,
obviously, '1646' somehow refers to a date. After a little guesswork
and experimentation, it turns out that these values represent the
number of days between a given date and January 1, 2000.
In order to use the same scheme in BetterCalendar, a DateTime constant and two methods are defined:
private static readonly DateTime DayCountBaseDate = new DateTime(2000, 1, 1);
private int DayCountFromDate(DateTime date)
{
return ((TimeSpan) (date - BetterCalendar.DayCountBaseDate)).Days;
}
private DateTime DateFromDayCount(int dayCount)
{
return BetterCalendar.DayCountBaseDate.AddDays(dayCount);
}
For the next and previous month post back links, the argument is prefixed with the letter 'V':
javascript:__doPostBack('Calendar1','V1613')
which means "change the visible month to June 1, 2004".
For the post back links to select a week or the entire month, the
argument begins with the letter 'R' followed by the day count number,
and finally, two digits representing the number of total number of days
to be selected:
javascript:__doPostBack('Calendar1','R164607')
which means "select seven consecutive days starting with July 4, 2004".
The RaisePostBackEvent event implemented in BetterCalendar
handles parsing this argument and performing the appropriate action
(changing the visible month or selecting a date or range of dates).
Storing Non-selectable Dates
Within the BetterCalendar.Render method, a System.Web.UI.WebControls.CalendarDay and a System.Web.UI.WebControls.TableCell object is created for each day in the calendar display. The OnDayRender event is raised and these two objects are passed to any DayRender event handler assigned to the control, just like Calendar does.
After control returns from the event handler, the CalendarDay.IsSelectable property is checked. If it was set to false, that day's date is added to an ArrayList.
ArrayList nonselectableDates = new ArrayList();
for (...)
for (...)
...
CalendarDay day = this.Day(date);
TableCell cell = this.Cell(day);
this.OnDayRender(cell, day);
if (!day.IsSelectable)
nonselectableDates.Add(day.Date.ToShortDateString());
The obvious thing to do would be to save this list to the view
state. However, since the control is being rendered, this will not work
because the control's SaveViewState method has already been called.
Instead, the data is stored in a hidden field added to the page. A
couple of methods are defined to handle the conversion of the dates in
the ArrayList to a suitable string value that can be stored in a hidden form field and subsequently restored.
private void SaveNonselectableDates(ArrayList dates)
{
string[] list = new string[dates.Count];
for (int i = 0; i < list.Length; i++)
list[i] =
this.DayCountFromDate(DateTime.Parse(dates[i].ToString())).ToString();
string fieldName = this.GetHiddenFieldName();
string fieldValue =
HttpUtility.HtmlAttributeEncode(String.Join(",", list));
this.Page.RegisterHiddenField(fieldName, fieldValue);
}
private ArrayList LoadNonselectableDates()
{
string fieldName = this.GetHiddenFieldName();
string fieldValue = this.Page.Request.Form[fieldName];
string[] list = fieldValue.Split(',');
ArrayList dates = new ArrayList();
foreach (string s in list)
dates.Add(this.DateFromDayCount(Int32.Parse(s)));
return dates;
}
private string GetHiddenFieldName()
{
return String.Format("{0}_NonselectableDates", this.ClientID);
}
Within the RaisePostBackEvent, when a range of dates is being selected, we can load this list and use it to remove those dates.
...
this.SelectedDates.Clear();
this.SelectedDates.SelectRange(date, date.AddDays(n - 1));
if (!this.SelectAllInRange)
{
ArrayList nonselectableDates = this.LoadNonselectableDates();
foreach(DateTime badDate in nonselectableDates)
this.SelectedDates.Remove(badDate);
}
History
- April 19, 2004
- May 14, 2004
- Update to improve globalization support. Month and day names and
abbreviations, date formatting and the default first day of the week
are now based on the current culture.
- May 24, 2004
- Fix for a bug where the
SelectionChanged event was not always
being raised when a week or month was selected.
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Rant 
Admin