Integrate your Web applications with your users' personal calendars.

I'll be the first to admit that I'm aging. How old am I? Well, that's a secret that I may divulge at the end of the article. But with age comes organization. Work days become hectic, and sometimes I need a reminder of what I'm supposed to do next. I'm sure some of your users need reminders at times too. That's where the concept of this article started.

Imagine this scenario. A user is on the phone with a customer, trying to resolve an issue. The user is logging the call on the system and indicates that she has promised to give a follow-up call in two days. Finally, the user puts a reminder on her personal calendar to call the customer back.

From Lotus Notes to Microsoft Outlook, email clients today include a calendar application. These calendar applications have built-in support for a file format named iCalendar. In the above scenario, the use of an iCalendar file could have eliminated the final step of manually adding the reminder to the user's personal calendar application.

The iCalendar file format is simply a plain-text file with an .ics extension. The file must always begin with BEGIN:VCALENDAR, and the last line of the file must always be END:VCALENDAR. Everything between the BEGIN and END lines represents the body of the iCalendar file.

Notice that the BEGIN and END statements are followed by the word VCALENDAR. The iCalendar file format is derived from the vCalendar file format. The VCALENDAR attributes were retained to maintain compatibility.

The basic file layout for an iCalendar file is illustrated in Figure 1.

Figure 1: This code illustrates the basic structure of an iCalendar file.

The BEGIN:VEVENT represents the beginning of the event. The DTSTART and DTEND attributes provide the starting and ending dates and times. The DTSTAMP shows the date and time the reminder was created. The DESCRIPTION and SUMMARY attributes provide a detailed description and a subject for the reminder.

The BEGIN:VALARM is the beginning of the reminder alarm attributes. In the above example, it is set to remind the user 15 minutes before the start time.

Figure 2 illustrates how to change the basic iCalendar file into a file that can be used in a CGIDEV2 Web application:

Figure 2: Make these changes to the iCalendar file for use in CGIDEV2.

I've added a section name of remindme-top, as well as the content-type declaration for an iCalendar file. I've also replaced the starting date, ending date, current date, current time, description, and subject with variables. These variables will be populated in an RPG program.

The RPG program REMIND1 will display a Web page where the user can enter a subject, reminder date, and description. When the user submits the Web page, another RPG program will build an iCalendar file and allow the user to open the file. The file will open in the user's default program that handles .ics files. The source for the REMIND1 program is shown in Figure 3.

Figure 3: Here's the source for the RPG program REMIND1.

Notice that the RetrieveHTML subroutine in the REMIND1 program loads the file REMINDER.HTM from the IFS. The source for the REMINDER.HTM is shown in Figure 4.

Figure 4: This is the REMINDER.HTM source used in the REMIND1 RPG program.

Figure 5 shows the results of running the REMIND1 program in your browser.

Figure 5: This screen shot shows the Web page built in the REMIND1 RPG program. (Click image to enlarge.)

The REMINDER.HTM file contains two JavaScript functions in the header: prototype.js and calendarimport.js. Together, these two JavaScript functions are used to build the iCalendar file to be imported.

The function prototype.js is known as the Prototype JavaScript Framework. It is one of many JavaScript frameworks that can be used to ease the implementation of AJAX. This JavaScript function can be downloaded from the Prototype Web site at www.prototypejs.org.

The calendarimport.js function retrieves the values on the HTML form and calls another RPG program named REMIND2. Figure 6 shows the source for the calendarimport.js function.

function calendarimport() {

var xRandomString = $F('randomstring');

var xSubject = $F('subject');

var xRemindDate = $F('rdate');

var xNotes = $F('notes');

var url='remind2.pgm?subject=' + xSubject + '&note=' + xNotes +               '&reminddate=' + xRemindDate + '&randomstring=' + xRandomString;

new Ajax.Request(url , {method: 'get'});

window.open('/temp/' + xRandomString + '.ics');

return false;

}

Figure 6: Here's the source for the calendarimport.js JavaScript function.

The variables xRandomString, xSubject, xRemindDate, and xNotes are populated using the Prototype function $F. The $F function simply retrieves the values of the form fields in an HTML document. Notice that the form only has three visible input fields: subject, reminder date, and description. In the REMINDER.HTM, there is a fourth field that is hidden called randomstring. The program REMIND1 populates this hidden field with a random string of 20 characters using the CGIDEV2 RandomString procedure. This random string will become the name of the iCalendar file stored in the system.

The variable url is constructed to call the REMIND2 program, passing it the expected variables and contents entered on the form.

The Ajax.Request function is a Prototype function that can be used to call another RPG program. In this case, the url constructed in the prior line is called.

Finally, a new browser window is opened that will allow the user to open the iCalendar file.

The REMIND2 program called in the calendarimport.js JavaScript function will need to retrieve the iCalendar shell stored on the IFS, retrieve the values passed into the program  (subject, reminder date, notes, and the random string), populate the variables in the iCalendar shell, and then save the iCalendar file to the IFS. Figure 7 shows the source for the REMIND2 program.

Figure 7: The REMIND2 program builds the iCalendar file and saves it to the IFS.

One additional change is required in order to be able to open the iCalendar file. The configuration for the HTTP server will need to be changed so that it will recognize the .ics file. The content type of the iCalendar file is text/calendar. If this type is not already defined in the Apache configuration file, it will need to be inserted. Simply add the following line to your configuration file:

AddType text/calendar .ics

Integrating a Web application with a user's personal calendar can be an integral part of any successful application. By using CGIDEV2, the Prototype Framework, and an iCalendar file, it's never been easier.

Oh, and I almost forgot. At the time I'm writing this, I'm a youthful, but graying, 42.

Also Read

Advanced/Free - Function Calls and Return Values

PRACTICAL ILE - ILE Service Programs

Data-Manipulation Operations Using Free Format, Part Two