DateTimeListPicker Web User Control for .NET 2.0

This is my first attempt at a serious web user control.  It's an interface for selecting a date and (optionally) a time using drop-down lists.  I like this interface because when used via the keyboard it provides almost random access to any date.

You are welcome to use this control, provided that you retain the credits in the source code.

Installing

How to install:

  1. Click here to download the source code (DateTimeListPicker.zip, 6KB).
  2. Add DateTimeListPicker.ascx and DateTimeListPicker.ascx.vb to your web project.
  3. Open the aspx page onto which you want to place a DateTimeListPicker control.
  4. Add this directive to the aspx page source (change the Src attribute to point to your copy of the ascx file):
    <%@ Register Src="~/DateTimeListPicker.ascx" TagName="DateTimeListPicker" TagPrefix="CGJ" %>
  5. Add this element at the position where you want the date list boxes to appear:
    <CGJ:DateTimeListPicker ID="DateTimeListPicker1" runat="server" />

Run the page and you should see three drop down list boxes, allowing you to select a day, month and year.  If you submit your page to the server, you should have access to the selected date through the DateTimeListPicker1.Value property.

Customising

The control can be customised in many different ways.  Here are the properties that you can set:

  • ShowTimeOfDay - displays two extra drop-down lists in which you can select the hour and minute of the day
  • AllowBlanks - adds a blank item to the top of each list.  The IsBlank property tells you whether all the boxes have been left blank
  • TabIndex - works just like the TabIndex property for regular controls
  • CssClass - works just like the CssClass property for regular controls
  • Enabled - works just like the Enabled property for regular controls
  • EnableViewState - works just like the EnableViewState property for regular controls
  • DateBoxSpacing - specifies the spacing between the day, month and year drop-down list boxes
  • DateTimeSpacing - specifies the spacing between the year and hour drop-down list boxes
  • YearListMinValue - specifies the first value in the year list
  • YearListMaxValue - specifies the last value in the year list
  • MinuteListFirstValue - specifies the first value in the minute list.  The default is 0.
  • MinuteListInterval - specifies the increment between successive items in the minute list (up to 59).  The default is 1.
  • Value - as well as reading the date posted by the user, you can set the date selection through the Value property default or in your code.

Often you will be able to use the control without enabling ViewState.  Note that, like other controls, the ValueChanged event doesn't work correctly when ViewState is disabled.

NOTE: The control's ViewState footprint is actually pretty small.  Enabling ViewState for the DateTimeListPicker control does not enable ViewState for all of its lists!  Their ViewState is always disabled.

Adding client-side validation and events

The control provides some handy methods to help you perform client-side validation and to run client-side script in response to changes in the control's value.  For example, suppose your form uses two DateTimeListPicker controls called dlpFrom and dlpTo to specify a date range (from x to y).  You can verify on the client side that the From and To dates are valid, and that the To date comes after the From date.  You can also change the To date when the From date selection changes, in order to help the user to enter the desired date range.

Here's the code to perform the automatic update of the To date (put this in Page_Load):

dlpFrom.RegisterValidatorScript()
dlpFrom.AddOnChangeScript("if(DateTimeListPicker_IsValid(""dlpFrom"") && (!DateTimeListPicker_IsValid(""dlpTo"") || DateTimeListPicker_GetDateTime(""dlpTo"") < DateTimeListPicker_GetDateTime(""dlpFrom""))) DateTimeListPicker_SetDateTime(""dlpTo"", DateTimeListPicker_GetDateTime(""dlpFrom""))")

That looks like a bit of a mouthful, but it simply says 'Each time the From date selection changes, if the selection is a valid date and it comes after the To date (or the To date is invalid), then set the To date to be the same as the From date'.  With a slightly more complicated statement you could use the JavaScript Date.setDate() method to set the To date to 'From date plus 2 days', for example.

©2009 Carl Johansen