onsider the scenario in which you are building a Web application that displays events or appointments for different dates. If you want your users to remember this event within their local desktop email/calendar application?such as Outlook, so that they can be reminded about it, your users are faced with a manual task: They have to manually create a new appointment in Outlook and copy all the information to create a new appointment. In this article, we shall see how you can provide a clickable appointment feature within your apps. All the user has to do is to click on the given link and an appointment is created automatically within their local desktop e-mail/calendar application.

Our solution uses the vCalendar format, a powerful new approach to Personal Data Interchange (PDI). PDI occurs every time individuals communicate, in either a business or personal context. These interchanges frequently include the exchange of information, such as business cards, telephone numbers, addresses, etc. The vCard and vCalendar features facilitate PDI electronically.



Creating a new appointment in Outlook based on information visible in a browser is a manual process. Automate this process by providing your users with a clickable appointment feature that automatically copies the appointment information into their desktop e-mail/calendar application.



A manual demonstration
Dissecting the vCalendar file
Using vCalendar in your Web applications

vCalendar is a text-based format published by the Internet Mail Consortium (IMC)?an international organization focused on (as their Web site reports) “cooperatively managing and promoting the rapidly-expanding world of electronic mail on the Internet.” The vCalendar format allows different software packages to share information about calendar events using a simple ASCII text format. As of last count, numerous software packages including Outlook, Lotus, and Eudora had support for the vCalendar format. You can find details of this format in this white paper.

A Manual Demonstration

Figure 1. Clicking the Calendar graphic invokes a Drop Down calendar in place.

Let us see how the vCalendar format works. The easiest way to do this is to do a manual test first before we figure out how to incorporate it within a browser-based Web application. Let’s use Outlook for this manual test.

• Within Outlook, create a new appointment for any given day. Fill in all the appointment details:date, time, event location as well as event body details. Do not invite anybody to the event.
• Click “save” so that it gets added to your Calendar. Now, open the appointment.
• From the File menu, select Save As.
• In the “Save as type:” list, select “vCalendar Format (*.vcs)”
• Save the file as “C: emp est.vcs”.
• Close the appointment.
• Finally, before you proceed, DELETE the appointment from your calendar so you do not have it anymore within your system.

Now let’s test to see how a browser reacts to the vCalendar format. Open your favorite HTML editor and create the following HTML file:

	This is an Event. Here are the details
Click here to add this event to your Calendar

Save the file as “C: emp est.htm”. As you can see, there is a hyperlink within the file that points to the vcs file created from Outlook.

Now, open your browser and navigate to the html file “C: emp est.htm”. You should see your html document. Click on the hyperlink and watch what happens. The vcs file is downloaded to your browser and it automatically opens up Outlook and creates an appointment in your calendar from the vcs file.

Dissecting the vCalendar File
The vCalendar format utilizes data normally stored within a calendaring and scheduling application, facilitating the cross platform exchange of information about items such as events and to-do’s. An event is a calendaring and scheduling entity that represents a designated amount of time on a calendar. For example, it may be an activity, such as a two-hour project team meeting from 9am to 11am, on Tuesday, January 23rd. A to-do is a calendaring and scheduling entity that represents an action item or assignment. vCalendar can be used to transport personal calendaring information between applications of your choice whether they are personal information managers, e-mail systems, or Web browsers. Once the information is on your system, you can share it with other vCalendar-enabled application with desktop interaction techniques such as the clipboard and drag-‘n’-drop.

Let’s take a look at the vCalendar file we created. As you can see, you can open it up in Notepad since it is a text file. Here’s what it looks like:

PRODID:-//Microsoft Corporation//Outlook 9.0 MIMEDIR//ENVERSION:1.0BEGIN:VEVENTDTSTART:20010507T183000ZDTEND:20010507T190000ZLOCATION;ENCODING=QUOTED-PRINTABLE:Test LocationUID:040000008200E00074C5B7101A82E00800000000804CA453F2D6C0010000000000000000100 00000D853B7630442D51188850060974F9E6CDESCRIPTION;ENCODING=QUOTED-PRINTABLE:This is a Test Event.=0D=0AHere are i=ts details=0D=0AThis event has been added from a vCalendar format file=0D==0Ausing a browser based web application.=0D=0A=0D=0ACool huh?=0D=0ASUMMARY;ENCODING=QUOTED-PRINTABLE:Test EventPRIORITY:3END:VEVENTEND:VCALENDAR

A vCalendar file is enclosed within the “BEGIN:VCALENDAR” and “END:VCALENDAR” tags. Within that, the actual event is enclosed within the “BEGIN:VEVENT” and “END:VEVENT” tags. The IMC Web site ( http://www.imc.org) contains a full description of the vCalendar format.

The actual event is described using the following tags:

• DTSTART and DTEND denote the starting and ending date/times for the event. These tags use the format: YYYYMMDDThhmmssZ where YYYY = year, MM = month, DD = date, T = start of time character, hh = hours, mm = minutes, ss = seconds, Z = end of tag character. The entire tag uses Greenwich Mean Time (GMT) to express the date/time of the event so remember to adjust your event times accordingly.
• LOCATION;ENCODING=QUOTED-PRINTABLE indicates the location
• SUMMARY;ENCODING=QUOTED-PRINTABLE indicates the subject
• DESCRIPTION;ENCODING=QUOTED-PRINTABLE indicates the description

In addition, you can use other tags such as CATEGORIES and PRIORITY to add categories to the event or signify its priority. The vCalendar format documentation available at the IMC Web site can help you identify all the tags.

Using vCalendar in a Web Application
Now that we know what a vcs file looks like we can plan to use it in our Web application. Consider a scenario in which we are listing events on our Web site based on data from a database. The pseudocode for this app would be as follows:

Open a connection to the databaseObtain a list of eventsFor each event	Dump its details within a table row in HTML formatNext event

This article does not deal with displaying events from a database. We have seen other 10-Minute Solutions that show you how to access data from a database and display it. We could therefore add a hyperlink to each event that allows a user to add the appointment to their calendar application.

Assume that we have a table containing events with the following structure:

Event_IDEvent_Begin_DateEvent_End_DateEvent_TitleEvent_LocationEvent_Description

We can then use this code to dump the events in a list:

Do while not objRS.EOF	Response.Write ""	Response.Write "" & _			objRS("Event_Title") & ""	Response.Write "" & _	FormatDateTime(objRS("Event_Begin_Date"), 2) & _			"- to - " & _	FormatDateTime(objRS("Event_End_Date"), 2) & ""	Response.Write "" & _			objRS("Event_Location") & ""	Response.Write "" & _			objRS("Event_Description") & ""	Response.Write ""					objRS.MoveNextLoop

This would produce a list of events with their titles, begin and end dates, location and description.

Title	Begin Date - to - End Date	Location	Description

We can now add a link that allows users to automatically add the event to their appointments. To do this, add a hyperlink to a special ASP page that will return the text of the vcs file given a valid Event ID. In our example, we will be creating a new ASP page called “GetVCS.asp” that will return a vcs file back to the browser on demand.

We therefore modify the ASP code above to add a hyperlink to our “GetVCS.asp” page:

Do while not objRS.EOF	Response.Write ""	Response.Write "" & _			objRS("Event_Title") & ""	Response.Write "" & _	FormatDateTime(objRS("Event_Begin_Date"), 2) & _			"- to - " & _	FormatDateTime(objRS("Event_End_Date"), 2) & ""	Response.Write "" & _			objRS("Event_Location") & ""	Response.Write "" & _			objRS("Event_Description") & ""	Response.Write "" & _	"Add"	Response.Write ""					objRS.MoveNextLoop

This will produce the same listing as before, but for every event, there will now be a hyperlink to add the event to the user’s appointments.

Title Begin Date - to - End Date	Location Description	Add

Clicking on the “Add” hyperlink will add the event details to the user’s appointment program. Now let us see how the hyperlink generates a vCalendar on the fly.

Generating vCalendar Formats on the Fly
Remember, our GetVCS.asp page expects one argument (id) passed via the query string?this indicates the event id for the event we need a vCalendar for. Our ASP page therefore accesses the same event details as our event-listing page and dumps the content of a single event to the browser in a vCalendar format.

Within our ASP page, we obtain the value of our event id from the Request object and make sure it is not a blank value.

Dim mlngEventID		mlngEventID = Request("id")	If mlngEventID = "" Then		Response.Write "No Event ID found. Unable to Proceed"		Response.End	End if

We then obtain a recordset containing the event details for the event id provided to us:

Dim strSQL, objRS		strSQL = "Select * from tblEvents where Event_ID = " & mlngEventID	set objRS = GetRecordSet(strConnString, strSQL)

The above code uses a custom function GetRecordSet that accepts a connection string to a database and a valid SQL statement and returns a recordset object containing the results.

We then build our vCalendar format from the recordset data:

Dim strvCalendar		strvCalendar = BuildVCalendar(objRS)

“BuildVCalendar” is a user-defined function that we write within our ASP page that accepts a recordset object and returns the event data in a vCalendar format. returned string. We next send the returned string back to the browser, informing the browser that we are sending vCalendar data:

Response.ContentType = "text/x-vCalendar"	Response.AddHeader "Content-Disposition", _		"filename=Event" & mlngEventID & ".vcs;"	Response.Write strvCalendar	Response.End

The first line tells the browser that the content being sent is of type “text/x-vcalendar”. This allows the browser to prepare the application to accept the content. The second line tells the browser the name of the file being sent (EventXX.vcs where XX = event id). Finally, we send our vCalendar format string and end our application.

The “BuildVCalendar” routine takes the values from the recordset and builds a long string in the vCalendar format:

Function BuildVCalendar(byval objRS)	' - configure our Time Zone Factor. Set this to the value	' - that needs to be added/subtracted from the date/time	' - to convert the event date/time to GMT time	' - base it on your Web Server's time zone	' - In my case, Eastern Time is 5.5 hours behind GMT so	' - to get GMT, I need to add 5.5 hours	CONST TIMEZ0NE_FACTOR = +5.5	Dim dtStart, dtEnd, strSubject, strLocation, strDesc		' -- Assuming Event_Begin_Date and Event_End_Date hold	' -- Date and Time values	dtStart = DateAdd("h",TIMEZONE_FACTOR, objRS("Event_Begin_Date"))	dtEnd = DateAdd("h",TIMEZONE_FACTOR, objRS("Event_End_Date"))			' -- Format it properly as YYYYMMDDThhmmssZ	dtStart = 	Right("0000", Year(dtStart), 4) & _				Right("00" & Month(dtStart), 2) & _				Right("00" & Day(dtStart), 2) & _				"T" & _				Right("00" & Hour(dtStart), 2) & _				Right("00" & Minute(dtStart), 2) & _				Right("00" & Second(dtStart), 2) & _				"Z"		dtEnd = 	Right("0000", Year(dtEnd), 4) & _				Right("00" & Month(dtEnd), 2) & _				Right("00" & Day(dtEnd), 2) & _				"T" & _				Right("00" & Hour(dtEnd), 2) & _				Right("00" & Minute(dtEnd), 2) & _				Right("00" & Second(dtEnd), 2) & _				"Z"	' -- 	strSubject = objRS("Event_Title")	strLocation = objRS("Event_Location")	strDesc = objRS("Event_Description")			BuildVCalendar = 	_"BEGIN:VCALENDAR" & vbCrlf & _	"VERSION:1.0" & vbCrlf & _	"BEGIN: VEVENT" & vbCrlf & _	"DTStart:" & dtStart  & vbCrlf & _	"DTEnd:" & dtEnd  & vbCrlf & _	"SUMMARY;ENCODING=QUOTED-PRINTABLE:" & strSubject & vbCrlf & _	"DESCRIPTION;ENCODING=QUOTED-PRINTABLE:" & strDescription & vbCrlf & _	"Location;ENCODING=QUOTED-PRINTABLE:" & strLocation & vbCrlf & _	"UID:" & objRS("Event_ID") & dtStart & strSubject & vbCrlf & _	"PRIORITY:3" & vbCrlf & _	"End:VEVENT" & vbCrlf & _	"End:VCALENDAR" & vbCrlfEnd Function

And there you have it. You now have a generic utility ASP page that can return any event in a vCalendar format. You can use it within one or more Web apps with minor changes.