When you think ASP, think...
Recent Articles
All Articles
ASP.NET Articles
ASPFAQs.com
Message Board
Related Web Technologies
User Tips!
Coding Tips
Search

Sections:
Book Reviews
Sample Chapters
Commonly Asked Message Board Questions
JavaScript Tutorials
MSDN Communities Hub
Official Docs
Security
Stump the SQL Guru!
Web Hosts
XML
Information:
Advertise
Feedback
Author an Article

ASP ASP.NET ASP FAQs Message Board Feedback
 
Print this Page!
Published: Wednesday, June 4, 2008

Picking Dates with a Free RJS PopCalendar, a Free ASP.NET Popup Calendar Control

By Scott Mitchell


Introduction


A common user interface element for entering date values is a popup calendar. For example, virtually all travel and booking websites prompt for dates using a textbox that, when clicked or focused, displays a calendar that hovers above the rest of the content on the page. Upon clicking a date from the calendar, it disappears and the date value appears in the textbox. Some websites require that the date be chosen from the calendar; others allow the user to either type in the date or pick it from the calendar.

There have been two previous articles on 4Guys that examined how to create a popup calendar control from the ground up. In Populating Form Inputs Using the Calendar Control, James Avery showed how to have a Calendar appear in a popup window opened via JavaScript's window.open function. Scott D. Smith showed how to use the Microsoft ASP.NET AJAX framework's PopupControlExtender to display the Calendar control in Creating an AJAX-Enabled Calendar Control. There are also a number of third-party Web control vendors that ship popup Calendar controls, which you can peruse at the Date, Time, and Calendar section of the ASP.NET Control Gallery.

I recently worked on a project that used the free RJS PopCalendar control and was impressed with its features and ease of use. This article shows how to add RJS PopCalendar to your ASP.NET web applications and demonstrates some of its functionality. Read on to learn more!

- continued -

A Quick Overview of RJS PopCalendar


RJS PopCalendar is a free ASP.NET Web control created by Ricaute Jiménez Sánchez. It works with all versions of ASP.NET (1.x, 2.0, and 3.5), offers Designer support in Visual Studio, and is free. The download at the end of this article includes the PopCalendar assemblies and JavaScript files along with a number of demos. To get the latest version of the control or to report any bugs or other issues, visit http://code.msdn.microsoft.com/RJSPopCalendar.

The popup calendar user interface typically consists of two input controls: a textbox and the popup calendar. Some third-party popup calendar controls render both the textbox and popup calendar; others display only the popup calendar and must be associated with an existing TextBox control on the page. PopCalendar falls into the latter camp. To use PopCalendar on a web page you need to first add a TextBox control to the page. Next, add PopCalendar to the page and set its Control property to the ID of the TextBox control. PopCalendar renders a calendar icon on the page that, when clicked, displays a popup calendar. Selecting a date populates the associated textbox. We'll see an example shortly, but before we examine using the PopCalendar control in an ASP.NET page we need to first look at how to add the PopCalendar control and support files to a web application.

Adding the PopCalendar Control to an ASP.NET Web Application


The PopCalendar control and its functionality is made possible by two types of files:
  • The PopCalendar assembly - this is the .dll file that contains the control's compiled code. This file needs to be placed in your web application's /Bin folder.
  • Support files - these include JavaScript, CSS, and image files used by the PopCalendar control. You will need to add the folder containing these files to the root of your web applicaiton.
The PopCalendar download includes different assembly and support files for different scenarios. There are four different combinations of assembly and support files you can use:
  • ASP.NET 1.x Development in Visual Studio .NET 2002/2003 - Use the assembly named RJS.Web.WebControl.PopCalendar.dll, located in the Library folder. The support files are located in the folder named PopCalendar.
  • ASP.NET 2.0 Development in Visual Studio 2005 without Microsoft's ASP.NET AJAX Framework Installed - Use the assembly named RJS.Web.WebControl.PopCalendar.dll, located in the Library2005 folder. The support files are located in the folder named PopCalendar2005.
  • ASP.NET 2.0 Development in Visual Studio 2005 with Microsoft's ASP.NET AJAX Framework Installed - Use the assembly named RJS.Web.WebControl.PopCalendarAjax.Net.dll, located in the Library2005AjaxNet folder. The support files are located in the folder named PopCalendar2005AjaxNet.
  • ASP.NET 3.5 Development with Visual Studio 2008 - Use the assembly named RJS.Web.WebControl.PopCalendar.Net.2008.dll, located in the Library2008 folder. The support files are located in the folder named PopCalendar2008.
Copy the appropriate assembly to your application's /Bin directory and the appropriate support files folder to your application's root directory. You can optionally add PopCalendar to the Visual Studio Toolbox by right-clicking in the Toolbox and selecting Choose Items. This displays a dialog box of available items. Click Browse and then navigate to the assembly file in your application's /Bin folder. Using this file adds two controls to the Toolbox: PopCalendarMessageContainer and PopCalendar (see the screenshot below).

The PopCalendar control has been added to the Toolbox

The demo available for download at the end of this application was created with Visual Studio 2008. Therefore, you'll find the RJS.Web.WebControl.PopCalendar.Net.2008.dll assembly in the /Bin folder and the PopupCalendar2008 folder in the application's root directory.

Adding the PopCalendar Control to a Web Page


At this point your web application should have the PopCalendar assembly and support files located in the /Bin folder and the web application's root folder, respectively. Moreover, the PopCalendar control (and PopCalendarMessageContainer) should be present in Visual Studio's Toolbox. We are now ready to add the PopCalendar control to a page. Create a new ASP.NET page and start by adding a TextBox control to the page. This TextBox control will be used to display the user's date input. Next, drag the PopCalendar control from the Toolbox onto the page, placing it wherever you want the icon for displaying the popup calendar to appear. The final step is to wire the PopCalendar control to the TextBox. To accomplish this, set the PopCalendar control's Control property to the ID of the TextBox control.

After performing these steps your page's declarative markup should look similar to the following:

<%@ Page Language="VB" MasterPageFile="~/Site.master" AutoEventWireup="false" CodeFile="Demo1.aspx.vb" Inherits="Demo1" title="Untitled Page" %>
<%@ Register assembly="RJS.Web.WebControl.PopCalendar.Net.2008" namespace="RJS.Web.WebControl" tagprefix="rjs" %>

...

Choose a Date:
<asp:TextBox ID="ChooseDate" runat="server" Columns="10"></asp:TextBox>
<rjs:PopCalendar ID="myPopCal" runat="server" Control="ChooseDate" />

First take note of the first two lines of the declarative markup. Here you'll find the @Page directive and a @Register directive. The @Register directive was automatically added when you dragged the PopCalendar control from the Toolbox onto the page. It associates a particular tag prefix (rjs, in this case) with an assembly and namespace. Further down in your markup you should see the syntax for the TextBox control (named ChooseDate here) along with the markup for the PopCalendar control - <rjs:PopCalendar ID="myPopCal" runat="server" Control="ChooseDate" />. Note that the PopCalendar control's Control property is assigned the ID of the TextBox control, ChooseDate.

Visit the page through a browser. As the screenshot below shows, the PopCalendar control renders as a small calendar icon. This image file, as well as the JavaScript used to popup the calendar, is located in the appropriate support files folder (~/PopCalendar2008, in my demo). If the support file folder is not present, incorrectly named, or is missing required files, a client-side alert box is displayed explaining the problem.

PopCalendar renders as a small calendar icon.

Clicking the calendar icon displays a popup calendar that, by default, shows the current date and month. Users can jump to the next or previous month by clicking the right or left arrows in the upper left corner. Alternatively, they can choose a particular month or year to jump to from the drop-down lists at the top of the calendar. The current date is colored red.

Clicking the calendar icon displays a popup calendar.

After clicking on a date from the calendar control the popup calendar disappears and the selected date is displayed in the associated textbox.

The selected date is displayed in the TextBox.

As the above screenshot shows, the selected date is formatted as dd mm yyyy. You can change this format via the PopCalendar's Format property. To have it display the month before the day, set the Format property to mm dd yyyy. (When specifying the date use a space between the various date parts. To indicate what character actually separates each part, use the Separator property. The Separator property defaults to a dash.)

Preventing Invalid Dates A good popup calendar lets the end user enter the date value either by typing in the date directly or by picking the date from the popup calendar. One challenge with allowing a user to type in the date, however, is that the entered date may be invalid. That is, when picking a date from a calendar the user cannot pick an invalid date, but when typing in a date they may accidentally enter an alphabetic character or transpose two digits, resulting in a date like 05-0r-2008 or 50-06-2008. The good news is that PopCalendar automatically applies validation to the input entered by the user into its associated TextBox control. (Client-side validation is applied by default; to perform server-side validation call the PopCalendar control's Validate method, which returns a Boolean value indicating whether the control's assocaited date value is valid.)

For example, if a user types in a date of "Scott," upon tabbing out of the TextBox the PopCalendar displays the message "Invalid Date" directly the TextBox control and clears out the just-entered invalid value. You can customize the message displayed by PopCalendar when an invalid date is entered by using the control's InvalidDateMessage property.

If the date value is required, set the PopCalendar control's RequiredDate property to True. If this property is set to True and the user attempts to submit the form without having supplied a date value, the message "Required Date" is displayed beneath the TextBox. To customize this output, set the RequiredDateMessage property.

Any status messages generated by PopCalendar are displayed beneath the control's associated TextBox. To locate the messages elsewhere on the page, add a PopCalendarMessageContainer control to the page. (Recall that when we added the PopCalendar assembly to the Toolbox two controls were added: PopCalendar and PopCalendarMessageContainer.) After adding the PopCalendarMessageContainer control set its Calendar property to the ID of the PopCalendar control whose messages you want to display. The following declarative markup shows a PopCalendar control that requires a value in its TextBox and whose InvalidDateMessage and RequiredDateMessage properties have been customized. There's also a PopCalendarMessageContainer control that indicates where on the page the status messages are to be displayed.

Choose a Date: <asp:TextBox ID="ChooseDate" runat="server" Columns="10"></asp:TextBox>
<rjs:PopCalendar ID="myPopCal" runat="server" Control="ChooseDate"
   Format="mm dd yyyy"
   InvalidDateMessage="The date value entered is invalid." RequiredDate="True"
   RequiredDateMessage="You must enter a date value."
/>

...

<rjs:PopCalendarMessageContainer ID="PopCalMessages" runat="server" Calendar="myPopCal" />

The screen shot below shows the output when an invalid date ("Scott") is typed into the TextBox control.

PopCalendar displays a warning message when invalid dates are entered.

Limiting the Selectable Dates


PopCalendar includes a handful of properties that you can set to limit what dates the end user can select from the popup calendar (or type into the associated TextBox). For instance, to prevent the user from selecting a weekend date, set the control's SelectWeekend property to False. After making this change, the popup calendar displays a strikeout line through each weekend day, as shown in the screen shot below.

Unselectable dates are crossed off.

If you type in a weekend date into the associated TextBox control, the message "Weekends disabled" is displayed and the just-entered date is erased. (Use the PopCalendar control's WeekendMessage property to customize the status message displayed when entering a weekend date into the TextBox.)

You can also specify minimum and maximum date values via the PopCalendar control's From and To properties, respectively. The From and To properties each contain the following subproperties:

  • Control - set this property to the ID of another control on the page if you want to have that control's value dictate the legal from or to date.
  • Date - if the from or to date is based on a specific date, enter it here.
  • Increment - a positive or negative offset that is added to the to or from date from the associated control or specified via the Date subproperty in computing the actual to or from date.
  • Message - the status message to display if the date entered by the user falls outside of these bounds.
  • Today - a Boolean value indicating if the from or to date should be set to the current date.
The demo available for download at the end of this article includes a page that illustrates this functionality. The page contains two date fields to capture a departure date and a return date. The departure date cannot be on a weekend and must be from today's date or onward. The return date must be at least one day after the departure date. To implement this functionality I added two TextBox controls to the page and two PopCalendar controls. The PopCalendar control for the departure date has the Today subproperty of its From property set to True. The PopCalendar for the return date has two of its From subproperties configured:
  • The Control subproperty has been set to the ID of the departure date TextBox control, and
  • The Increment subproperty has been set to 1.
The net effect is that the return date must be at least one day in advance of the departure date, while the departure date must be today or in the future, but cannot be a weekend. The popup calendar control automatically strikes out invalid dates; if the user manually types in an invalid date an appropriate status message is displayed. The following screenshot shows the demo in action. The departure date is set to June 11th, a Wednesday. The return date calendar, then, strikes out all days that are not one day ahead of the departure date (all dates from June 11th and earlier).

The PopCalendar's from and to dates can be customized through a number of subproperties.

Conclusion


The popup calendar is a common user interface element for collecting date input. It presents the end user with the best of both worlds: the ability to type in the date into a textbox or to select a date from a hovering calendar. The PopCalendar control is a free ASP.NET popup calendar control created by Ricaute Jiménez Sánchez that works in all versions of ASP.NET. Not only does PopCalendar present the user with a popup calendar, but it also performs date validation on dates entered directly into its associated TextBox control. Furthermore, PopCalendar can be configured to disallow dates outside of a specified range. If you are in need of a popup calendar control for you ASP.NET application, give RJS PopCalendar a try.

Happy Programming!

  • By Scott Mitchell


    Further Reading:


  • RJS PopCalendar Download Site
  • Attachments:


  • Download the Demo Code Used in this Article



  • ASP.NET [1.x] [2.0] | ASPMessageboard.com | ASPFAQs.com | Advertise | Feedback | Author an Article