Home     About PeterBlum.com     Policies     Download a Licensed Product     Newsletter
Peter's Date and Time
SpecialDates Control
Back

The SpecialDates control enhances the DateTextBox and Calendar controls without adding its own HTML to the page. Use the SpecialDates control to define a list of dates which will have special behaviors.

Here are its features:


SpecialDates Control Attributes

SpecialDates is designed to deliver formatting and selection rules to other controls. Here are the attributes that help SpecialDates do its job.
  • You define list of as many dates as needed. If the list is empty, SpecialDates has nothing to contribute to other controls.
  • There are four types of date elements that you can add to the list:
    • Single date
    • Date range
    • Day of week - optionally limits it to a date range
    • Annual date - defines a date that repeats in the same month each year. Good for birthdays, anniversaries and holidays. Has rules to calculate the actual day of the month given a week number. For example, "Last Thursday of the month".
  • Each date element that you define has these attributes:
    • Selectable State - determines if the user can select the date or not. It also indicates if the date appears on the context and Help menus of DateTextBox and Calendar controls as a quick way to select it.
    • Style Sheet names - used by Calendar controls to change the appearance of the cell showing the date. There are two style sheet properties per date element. One for cells in the current month. The other for cells in other months.
    • Label - A name or short description of the date element. It has many uses:
      1. It automatically becomes a tooltip on the cell showing the date on Calendar controls.
      2. It can appear directly on the cell showing the date on Calendar controls as determined by the day cell formatting (see below).
      3. It becomes the label of the commands added to the context and Help button menus (as determined by the Selectable State).
      4. It can appear in the error message of the UnselectableDateValidator when the ErrorMessage property has the token {0}.
    • Description - A second textual element usually used for longer descriptions. Used only in the Calendar controls.
    • Time Rows - Dates often have several events on them. You can build a list of "Time Rows" with time, duration or end time, description and other values you have. These are formatted by the Calendar control.
    • Day cell formatting - used by Calendar controls to customize the HTML that appears within the cell showing the date. Use it to change colors, add images, links, and other formatting of the cell. There are several other powerful ways to format the data. (See below.)
  • The SpecialDates control provides default style sheet names and day cell formatting for any Calendar controls day cell that matches a date element. This simplifies the setup involved where many of your dates will use the same style sheets and day cell formatting.
  • You can set up the date and time data programmatically or from a Data Source.
  • If you provide multiple values for the same date, you can have it keep only the first or append their descriptions together.

Enhancements to DateTextBox

When you connect a DateTextBox to a SpecialDates control, you get these features:
  • DateTextBox can use any dates that you define as "unselectable" to report a validation error with the UnselectableDatesValidator if the user selects such a date.
  • You can define dates that appear in the context menu and Help menu for the user to quickly select that date. This allows you to add more than one "special date". This is an alternative to the QuickDateMenu that does something similar, but in a stand-alone menu.
  • Its popup Calendar will inherit all the information providing formatting and selection rules on each date. See the next section.

Here is the DateTextBox attached to the SpecialDates control. It has an UnselectableDatesValidator attached which will prevent entry of dates identified as unselectable. When you enter an unselectable date and tab off the field, you will see the validator in action. In addition, popup the calendar to see it with all the formatting.

...
 

<des:DateTextBox id="DateTextBox1"  SpecialDatesControlID="SpecialDates1" runat="server">
</des:DateTextBox> 
<des:UnselectableDatesValidator id="UnselectableDatesValidator1" runat="server" 
    ErrorMessage="The date cannot be selected because it is {DATELABEL}." ControlIDToEvaluate="DateTextBox1"
  <ErrorFormatterContainer>
    <des:TextErrorFormatter Display="Dynamic"/>
  </ErrorFormatterContainer>
</des:UnselectableDatesValidator>
<br>
<des:SpecialDates id="SpecialDates1" runat="server">
  <des:SpecialAnnualDate Label="Christmas" DayOffset="25" Month="12" 
     OtherMonthCssClass="DES_SDUnselectableOM1" CssClass="DES_SDUnselectable1" DayCellFormatting="{1}<br>{0}" />
   <des:SpecialAnnualDate Label="New Years Day" 
      OtherMonthCssClass="DES_SDUnselectableOM1" CssClass="DES_SDUnselectable1" DayCellFormatting="{1}<br>{0}" />
   <des:SpecialAnnualDate DayOfWeek="Monday" Label="Memorial Day (US)" Mode="DayOfWeek" WeekOffset="-1" Month="5"
      OtherMonthCssClass="DES_SDUnselectableOM1" CssClass="DES_SDUnselectable1" DayCellFormatting="{1}<br>{0}" />
   <des:SpecialDayOfWeek DayOfWeek="Sunday" Label="Closed"  
      OtherMonthCssClass="DES_SDUnselectableOM2" CssClass="DES_SDUnselectable2" />
   <des:SpecialDayOfWeek DayOfWeek="Monday" Label="Closed" 
      OtherMonthCssClass="DES_SDUnselectableOM2" CssClass="DES_SDUnselectable2"  />
</des:SpecialDates>


Enhancements to Calendars

When you connect a Calendar control to a SpecialDates control, you get these features:
  • The cells showing each date that matches a date in the SpecialDates control can offer these enhancements:
    • Make the cell unselectable.
    • Provide alternative style sheet names to change the appearance of the cells.
    • Provide tool tips on certain cells to annotate them.
    • Customize almost any aspect of the day cell. Use this to show descriptions, add graphics, alternative text, links, and more. There are several powerful formatters built into the Calendar control (shown below.)
    • Add a popup window that describes the day cell. Since it pops up, it can be much larger than the day cell inside the calendar, giving you the ability to show much more detail, including rows of time or event related information. Examples are shown below.
  • In addition, you can add commands to the context and help menus to go to a specific date.

Demos showing the day cell and popup window formatters

These demos will share a SpecialDates control with these date rules established:

  • September 9, 2006 will reflect a "Company Event" with a description, label, and list of time rows describing the activities at that event.
  • September 6, 2006 will contain the description: "Personel reviews due".
  • Christmas, New Years Day and Memorial Day are unselectable, use an alternative color, and show their names. While Christmas and New Years Day have fixed dates, Memorial Day is a US Holiday that always occurs on the last Monday of May. Note: This demo limits the holidays to a range of 10 years around the current date.
  • Sunday is unselectable, use an alternative color, and show "closed" on a tooltip.
<des:SpecialDates id="SpecialDates2" runat=server >
  <TimeRowTokens>
    <des:TokenDefinition TokenName="Activity" FormatString=""></des:TokenDefinition>
  </TimeRowTokens>
</des:SpecialDates>

Code in Page_Load      Language preference:
// Performance reviews due to Sept 6, 2006
SpecialDates2.AddDate(new DateTime(2006, 9, 6), PeterBlum.DES.SelectableState.Selectable,
   "", "Performance reviews due", PeterBlum.DES.AutoSortDuplicatesMode.Allow);

// Company event on Sept 9, 2006 with 4 time rows describing activities
PeterBlum.DES.Web.WebControls.SpecialSingleDate vSSD = SpecialDates2.AddDate(
   new DateTime(2006, 9, 9), PeterBlum.DES.SelectableState.Selectable,
   "End of summer bash. Bring your family and swimming trunks!", 
   "Company event", PeterBlum.DES.AutoSortDuplicatesMode.Allow);
vSSD.AddTimeRow(new TimeSpan(10, 0,0), "Activity", "Pool opens and drinks served");
vSSD.AddTimeRow(new TimeSpan(12, 0,0), "Activity", "Our own blues band performs");
vSSD.AddTimeRow(new TimeSpan(13, 0,0), "Activity", "Barbeque");
vSSD.AddTimeRow(new TimeSpan(21, 0,0), "Activity", "Fireworks");

// Holidays: Christmas, New years Day and Memorial Day (USA) which is the last monday of May
SpecialDates2.AddAnnualDate(12, 25, 2000, 2010, 
   PeterBlum.DES.SelectableState.Unselectable,
   "Holiday", "Christmas", "DES_SDUnselectable1", "DES_SDUnselectableOM1", "");
SpecialDates2.AddAnnualDate(1, 1, 2000, 2010, 
   PeterBlum.DES.SelectableState.Unselectable,
   "Holiday", "New Years Day", "DES_SDUnselectable1", "DES_SDUnselectableOM1", "");
SpecialDates2.AddAnnualDate(5, -1, DayOfWeek.Monday, 2000, 2010, 
   PeterBlum.DES.SelectableState.Unselectable,
   "Holiday", "Memorial Day", "DES_SDUnselectable1", "DES_SDUnselectableOM1", "");

// Sundays are closed
SpecialDates2.AddDayOfWeek(DayOfWeek.Sunday, 
   PeterBlum.DES.SelectableState.Unselectable,
   "Closed", "Closed", "DES_SDUnselectable2", "DES_SDUnselectableOM2", "");

Description format

Each day cell can show the Description text and offer a tooltip using the Label text.

Previous Month
Next Month
September 2006 Select a Different Month
SunMonTueWedThuFriSat
Closed27
2829303112
Closed3
45
Performance reviews due6
78
Company event9
Closed10
111213141516
Closed17
181920212223
Closed24
252627282930
Closed1
234567

<des:Calendar id="Calendar1" runat="server" SpecialDatesControlID="SpecialDates2" 
     DayCellWidth="100" WeekRowCellHeight="30"
     InitialMonthViewMode="InitialMonthView" InitialMonthView="2006-09-01" >
  <DayCellFormatter Format="Description">
  </DayCellFormatter>
</des:Calendar>

Row Count format

Each day cell shows the number of Time Rows, if there are any. By adding the token {DESC} to the header feature of day cells, the Description also appears. The Time Rows are only on September 9, 2006.

Previous Month
Next Month
September 2006 Select a Different Month
SunMonTueWedThuFriSat
Closed
 
27
2829303112
Closed
 
3
45
Performance reviews due
 
6
78
Company event
4 activities
9
Closed
 
10
111213141516
Closed
 
17
181920212223
Closed
 
24
252627282930
Closed
 
1
234567

<des:Calendar id="Calendar2" runat="server" SpecialDatesControlID="SpecialDates2" 
     DayCellWidth="100" WeekRowCellHeight="30" InitialMonthViewMode="InitialMonthView" InitialMonthView="2006-09-01" >
  <DayCellFormatter Format="RowCount">

     <RowCountFormatter Header="{DESC}" HideHeaderFooterOnEmptyBody="False" 
          MultipleRowsText="{COUNT} activities" OneRowText="1 activity">
     </RowCountFormatter>

  </DayCellFormatter>
</des:Calendar>

Time Rows format using the Popup Window

Each day cell uses the Row Count format, exactly like it was in the last example. This calendar also uses the Popup window, called the Expanded Date Formatter, to show the Time Rows. Point the mouse to September 9, 2006.

Previous Month
Next Month
September 2006 Select a Different Month
SunMonTueWedThuFriSat
Closed
 
27
2829303112
Closed
 
3
45
Performance reviews due
 
6
78
Company event
4 activities
9
Closed
 
10
111213141516
Closed
 
17
181920212223
Closed
 
24
252627282930
Closed
 
1
234567

<des:Calendar id="Calendar3" runat="server" SpecialDatesControlID="SpecialDates2" 
      DayCellWidth="100" WeekRowCellHeight="30" 
      InitialMonthViewMode="InitialMonthView" InitialMonthView="2006-09-01">
  <DayCellFormatter Format="RowCount">

     <RowCountFormatter Header="{DESC}" HideHeaderFooterOnEmptyBody="False" 
       MultipleRowsText="{COUNT} activities" OneRowText="1 activity">
     </RowCountFormatter>

  </DayCellFormatter>

   <ExpandedDateFormatter Format="Table" Title="{DATE}&nbsp;{DESC}" DateTokenFormat="AbbreviatedNoYear" >

      <TableFormatter Header="{LABEL}">

         <Columns>
           <des:LabelTRColumn HorizontalAlign="Right" Text="{TIME}" />
           <des:LabelTRColumn Text="{ACTIVITY}" />
         </Columns>

      </TableFormatter>

   </ExpandedDateFormatter>
</des:Calendar>


Back