Many offices have a calendar tacked to the wall in a central location. Employees add items such as scheduled vacations, reservations of conference rooms, or notices about meeting, conferences, or seminars. By using a shared calendar, employees can more efficiently coordinate their work with that of others in the organization. The groupware calendar script provides a Web interface to a similar shared calendar. Every user can read what other people have added and, if the script is configured to do it, can modify each other's entries. Calendar entries are stored in an ASCII database file.

The calendar has two primary views: the month view and the day view. In the month view, users can see calendar months for any year within a range specified at installation. Each day in the month displays the subjects of events scheduled for that day. In the day view, the events for a given day can be viewed in greater detail. Users can easily change the displayed month or year depending on their needs.

Varying levels of security are configurable. For example, the calendar can be made to be viewable by anyone or by authenticated users only. Items within the calendar database can be made to be modifiable or deletable only by the person who posts them or by everyone.

The application should be installed into the default directory, Calendar. Figure 13.1 outlines the expanded directory structure and the permissions of files and subdirectories.

This script should be placed in a directory that has permissions set to allow the Web server to read and execute and should expand to include three directories (Calendar_session_files, Library, and Databases) and two files (calendar.cgi and calendar.setup).

calendar.cgi is the application that provides most of the calendar processing. This file should be readable and executable by the Web server and will be discussed in greater detail in the design discussion.

calendar.setup is the file used to set the options and variables that pertain to your local setup. The file must be readable by the Web server and will be discussed in greater detail in the "Server-Specific Variables and Options" section.

Calendar_session_files is the subdirectory used by the authentication libraries to store session files, as discussed in Chapter 9. Initially the directory will be empty, but if it is set to be readable and writable relative to the Web server, it will continually fill up and be pruned as a part of daily usage.

Library is a subdirectory containing the supporting CGI libraries, which are discussed in Part Two. The subdirectory should be readable and executable by the Web server and should contain the following libraries, which should be readable by the Web server: auth-extra-html.pl, auth-extra-lib.pl, auth-lib-fail-html.pl, auth-lib.pl, auth-server-lib.pl, auth-fail_html.pl, cgi-lib.pl, cgi-lib.sol, date.pl, and mail-lib.pl.

Databases is a subdirectory containing the counter, events, and user files as well as any other calendar database files for alternative calendars. Because calendar.cgi must be able to write to this directory, its permissions should be set to be readable, writable, and executable.

calendar.counter is a text file used to keep track of unique ID numbers that have been assigned to each event in the calendar database. Initially, this file should contain the number 1 on the first line and nothing else. As time goes by, calendar.cgi will increment this number for every new entry. The file must be readable and writable by the Web server.

calendar.events is the datafile used to store all the entered events. The format is exactly the same as for the databases we have discussed in previous chapters, including the protocol for comment lines and the use of pipe (|) as a field delimiter. If you have jumped right to this chapter and do not understand the database format, read the section on the datafile in Chapter 11.

The default fields for the events file are as follows: the day, month, year, username, first name, last name, E-mail address, subject, event time, event description, and ID number. The file must be readable and writable by the Web server.

calendar.users is a file containing the list of users who are allowed to modify the events database. This user file is formatted exactly the same as the default user file discussed in Chapter 9. This file should be readable and writable by the Web server and should initially be empty.

Personal is a sample subdirectory used to describe how to create separate calendar databases to be displayed by the same calendar.cgi script. The directory contains three files: calendar.counter, calendar.events, and calendar.users. These files define all the specific formats of each separate calendar.

calendar.setup is the setup file used by calendar.cgi to define server-specific variables, configure authentication, and configure the events database. Defined variables are as follows.

$this_script_url is the location of calendar.cgi. Because we refer to it from here and because theoretically, this file will be in the same directory, you need only state the name of the script. If that is the case and if you don't change the name of the file, don't bother changing this variable.

$the_current_year is pretty obvious. Set this to the current year.

$greatest_year is the highest-numbered year for which you want people to be able to submit calendar events on the Add Item form.

$database_file is the location of the file that contains the calendar database. Because this file can be defined by the user, we tag onto this variable the value of $calendar_type, which is given to us by the main script, calendar.cgi. In short, $calendar_type is a value set by the initial link via urlencoding:

Thus, the $calendar_type should be the directory name of each separate calendar.

$counter_file is the path of the file that you are using to keep track of unique ID numbers. To make deletions and modifications, we must have a unique ID number so that the script can determine which database item to delete. These ID numbers should always be the last field in any database row. Again, because we need to isolate each of the calendars, we will reference the counter file including the $calendar_type variable.

$temp_file is a file that the script uses to temporarily store various data at various times. Unless you must, leave this file alone. The file will be generated and deleted by the script.

$lock_file is a file that the script uses to make sure that only one person can modify the database at any given time. Under no condition should you create this file yourself; the script will do it.

Authentication variables are explained in Chapter 9.

@day_names is an array containing the names of the weekdays. A word of caution for all the arrays: the most common source of configuration errors is to forget to put a comma here or a quotation mark there, or even to forget to add one of the fields. So be very careful here; everything must be perfect!

@month_names is—yup, you got it—a list of month names.

%MONTH_ARRAY is an associative array that pairs month names with their numbers.

%TIME is an associative array that pairs time names with military time values.

@time_values is an ordered list of military time values.

%FIELD_ARRAY is an associative array that pairs database field names with their variable names.

@field_names is the list of database fields.

@field_values is the list of the variable names associated with the database fields in @field_names. By the way, the reason that we don't use key and value commands to define the arrays relative to all the associative arrays is that we want to predefine an order for them. If we used keys and values, we would lose our order in the hash table entry to the associative array.

$field_num_time is the element number in the array of the event_time field in the database. We need this value to sort the database by time so that when you click on a day view, the day events come up in order. When setting this variable, remember that arrays count from zero and not from 1.

As an example, the complete calendar.setup file is listed next:

Once you have configured the setup file to the specifics of your server and calendar datafile, it is time to try out your installation. To reference the script, use the following URL format.

When clients click on this link, they should see the front page of your calendar with the default configurations. To reference separate calendar databases, the link to this script must have ?calendar=Some_subdirectory added at the end of the URL. For example,

Figure 13.2 outlines the logic of the script as it manages the needs of the client and the demands of the server.

The script begins by starting the Perl interpreter and printing the HTTP header.

Next, the script requires the necessary files using the subroutine CgiRequire at the end of this script. If there is a problem requiring files, this subroutine returns a message that's valuable for debugging. $lib is the location of the Library directory, where these files are to be stored; because it is hard-coded in the main script, you must be careful to change it here if you move the library elsewhere. Keep $lib equal to ./Library if you do not have a Library directory and are going to use the default directory included on the accompanying disk.

cgi-lib.pl is used to parse the incoming form data. By passing it (*form_data), the subroutine returns an associative array that we reference as $form_data{'key'} instead of $in{'$key'}. In the end, the script will reference all the incoming form data as $form_data{'variablename'}.

Once the incoming form data has been processed, the script determines which calendar database to use. If the calendar administrator has set up more than one calendar, each calendar database will be in a subdirectory, such as the example Personal Database that is included in the accompanying disk. To reference these separate databases, the link to this script must have ?calendar=Somesubdirectory added at the end of the URL. For example:

If the client does not submit a new database to use, the script will simply assign the default database and calendar. The $calendar_type variable will be used within the calendar.setup file, as addressed earlier.

Then the script defines all the calendar-specific variables by using the setup file, which you should have customized for your site.

Next, we make sure that the script "remembers" the $session_file so that it can continually check for authentication and keep track of the current client. However, if the client has already logged on, the script does not need to revalidate the client, because it will be getting the $session_file as form data (the same hidden field we are about to define). Thus, the script renames $form_data{'session_file'} to $session_file so that in both cases (the client's first time at this point or subsequent script access by a continuing client) it will have the session_id in the same variable name form.

The script also renames some other variables using the same principle. In doing so, the script uses a couple of routines in date.pl, as discussed in Chapter 6, to manipulate date information so that it can use the date information in a standardized way.

The script prints the dynamically generated calendar in two cases. First, the calendar is printed if the client has just logged on and is asking for the first page ($form_data{'session_file'} ne ""). Second, the calendar is printed if the client has already been moving through various pages and has asked to view the calendar again ($form_data{'change_month_year'} ne ""). The || means "or." If either case is true, the script may proceed.

The script begins outputting the calendar by first printing the HTML calendar header.

The script then prints the table header (Weekdays). Essentially, for every day (foreach $day) in our list of days (@day_names), the script prints the day as a table header.

Next, the script creates the variable $count_till_last_day, which it uses to make sure that it does not add too many <TR>s. Also, the script clears out a new variable, $weekday, which it uses to keep track of the two-dimensional aspect of the calendar: the script breaks the calendar rows after every seventh cell to represent a week. We will talk more about this later.

For every day in the mymonth array, the script creates a cell for the calendar. The array @mymonth, if you recall, is an array returned from the subroutine make_month_array.

The script begins by incrementing the two counter variables: $count_till_last_day and $weekday.

The script must also make sure that it adds a break for every week to make the calendar two-dimensional. Thus, when it has gone through sets of seven days in this foreach loop, it resets $weekday to zero. In the following code, the script uses these values to determine where it should place the </TR><TR>, making a new calendar row. When $weekday is greater than 6, the script knows that it needs a </TR><TR>, so by setting the $weekday flag to zero, we notify the script a few lines later to insert the row break.

Next, the script prints a table cell for each day. Because we want to make each of the numbers in each of the cells clickable so that someone can click on the number to see a day view, the script must manage a great deal of information here.

First, the script builds a variable called $variable_list, which is used to create a long URL appendix to transfer information using urlencoding. As we will discuss more specifically later, the routine that generates the day views needs to have the day, year, and month values if it is to bring up a day view. It must also have the $session_file value (as all the routines in this script must), the name of the calendar database, and the special tag view_day=on. So the script gathers all that information and appends it to the $variable_list variable.

Then the script creates the calendar cell. Notice that the number in each cell is made clickable by using urlencoding to tag the URL with all the variables we want passed.

The cell is not yet complete. The script must also grab from the calendar database the subject listings for all the entries on that day. In doing so, the script makes sure that, if it cannot open the database file, it sends a useful message to us for debugging. It uses the open_error subroutine in cgi-lib.sol, passing the routine the location of the database file.

If it successfully opens the database file, the script goes through each line, splitting the fields into their associated variables.

For every row searched, the script determines whether the day, month, and year of each item on that row are equal to the day, month, and year of the cell it is currently building.

If it was able to answer true to all the preceding conditions, the script knows that it has found a match and prints the subject in that cell.

Once the script has checked all the lines in the database, it closes that cell and moves to the next cell.

If, however, the script reached the end of a week row, it must begin a new table row for the next week. If $weekday is equal to zero, then the script knows that it is time to begin a new row. Otherwise, it continues with the row.

Before the script blindly prints another table row, it makes sure that it has not reached the end of the month. If $count_till_last_day equals @mymonth, it knows that there are no more days left and it should not begin a new row. Notice that when we reference @mymonth without quotation marks, we receive the numerical value of the number of elements in the array.

Once the script has finished making all the cells for the calendar, it prints the HTML footer.

To let the user select a different month to view, the script creates a select box using the subroutine select_a_month at the end of this script.

Likewise, it creates a select box that allows the client to choose a new year to view using select_a_year at the end of this script.

Then the script outputs the usual footer.

On the Web, the front page looks like Figure 13.3.

In the preceding routine, the script made every number in every cell of the calendar clickable so that the client could view the detailed descriptions of the events scheduled for that day. In the urlencoded string it built, the script included a tag view_day = on. Here is where that tag comes in handy. The following if test checks to see whether the person has clicked on a number; if the person has, the test will evaluate to true. If the test evaluates to true, the script prints the page header.

Next, the script opens the database again and looks for database rows that match the requested day, month, and year.

Just as it did in the routine for generating subject lines for day cells, the script pays attention only to database rows that match the client-defined day, month, and year.

Next, the script sets the $item_found flag so that it can keep track of whether it has found an item in the database.

The script then prints an <HR>-delimited, detailed list of events of the day, followed by a standard HTML footer.

If the script was not able to find any items in the database, it must let the client know. So if $item_found was never set to yes, the script sends the client a note of explanation.

Figure 13.4 shows the day view interface on the Web.

Allowing clients to view the calendar is one thing. Letting them modify the calendar database is another. The following routine checks to see whether the client is authorized to do anything in addition to viewing. The script passes GetSessionInfo, which is contained in auth-lib.pl, three parameters: the $session_file value (which will be nothing if one has not yet been set), the name of this script (so that it can provide links), and the associative array of form data we got from cgi-lib.pl.

The script then chops off the newline character for the last member in the array.

Once the client has been authenticated, the script determines the desired action. This first routine checks to see whether the client wants to add an item. If so, the script presents a form that the client uses to submit information for each of the database fields.

The subroutine submission_form at the end of this script is used to generate a form with input fields for every database item that can be manipulated by the client.

The script then prints a standard HTML footer and quits.

Figure 13.5 shows what the add form looks like on the Web.

Once the client submits a new event, the script must be prepared to add the item to the calendar database. The following routine does just that.

The routine begins by printing the page header.

Next, the script makes sure that the client has filled out all the necessary fields in the submission form. The script gets a list of the variable names (keys) associated with the associative array %form_data given to us by cgi-lib.pl.

For every element in the list array @form_data, the script checks to see whether the associated value in %form_data has content. If it doesn't, the script sends an error message and quits.

On the other hand, if the client entered data into all the fields, the script adds the new entry. First, it uses the subroutine GetFileLock in cgi-lib.sol to create a lock file to protect database integrity during modification. The script passes as the sole parameter the location of the lock file used by this program. If the script makes it past the lock file routine, it means that the script is the sole owner of the database file and can safely make changes.

Before it can add a new entry, though, the script must acquire a unique number from the counter file by using the subroutine counter in cgi-lib.sol. counter receives as its one parameter the location of the counter file used by this program.

Next, the script writes the contents of the new entry to the database file, appending (>>) the new data to the end of the existing list of items.

Then it formats the incoming form data so that the new event will be confined to one database line. To do this, the script changes (=~ s/) all occurrences (/g) of newlines (\n) into <BR>, and all occurrences of two hard returns (\r\r) into <P>.

Finally, the script simplifies some of the variables and generates the new database row.

The script now safely adds the new database row to the database file and deletes the lock file so that someone else may modify the database file.

Finally, the script prints the standard page footer.

Figure 13.6 shows the response on the Web.

We are not finished with the add quite yet. The script must also sort the entries in the database file so that when clients choose day views, their entries come out ordered by time. Again, the script creates the lock file so that no one else can modify the database file while it is being modified.

The script adds every row in the database file to an array called @database_fields.

Next, it creates a variable called $comment_row, which is used to hold comment lines in the database file. We do not want them sorted along with the rest of the items.

If the database row is not a comment row, the script finds the field that has the time of the event and appends it to the front of the database row. (So it occurs twice: once at the beginning of the line and again in the middle somewhere.) The script also adds (pushes) the whole string ($sortable_row) into a growing array called @database_rows. (We'll explain why in the next paragraph.)

When all the "modified" rows have been added to the array @database_rows, the script sorts the array. This is why we appended the time to the beginning of each of the rows: the sort routine sorts all the database items by event time.

Now the script goes through @sorted_temp_database and takes out the extra event_time string at the beginning of each database row, and we're back where we started except that the rows are sorted. The script splits the string at ~~ and then pushes the part of the string that corresponds to the original database row back into the array @final_sorted_database.

Next, the script modifies the original database file so that it represents the sorted order. To do this, it creates a temporary file to which it reprints all the comment rows stored in the variable $comment_row.

Then, for each of the database rows stored in @final_sorted_database, the script prints to the temporary file.

Finally, the script copies the temporary file over the original database file using the rename command so that the resulting file represents the sort. Then the lock file is deleted.

Next, if asked to do so, the script prints the modify event form.

First, it prints the basic header, including the hidden fields, which must be transferred to the modification routines so that they will have all the user information necessary to re-create database rows.

Because the modification routines will compare incoming form data to database row information, this information must come in with the rest of the form data.

The script then begins a table that will display all the items posted by the client on the day of interest. But, for the time being, instead of printing the table immediately, it builds it in a variable called $table.

Similarly, the script adds the header row to $table.

Then the script opens the database and checks for items that correspond to the user as well as the requested day, month, and year.

Next, it splits the database row as usual, but this time it also creates the list array @database_values, which will be discussed soon.

The script is directed to pay attention only to items specific to user, day, month, and year.

The script also flags the fact that it found an item.

Then the script continues adding to $table by adding the table row corresponding to the database row that was matched. Also, it adds a radio button so that the client can select the table row to modify.

If $item_found is still not equal to yes, it means that we did not match any items and that the script should send the client a note of explanation.

If, however, $item_found equals yes, the script prints $table.

In the case of modification, the client also needs a form similar to the add form so that he or she can make any desired modifications. We use the submission_form subroutine at the end of this script, passing it the parameter modify so that it will know to output that form.

Finally, the script prints a standard footer and quits.

On the Web, the modify form looks like Figure 13.7.

Next, the script prints a form for item deletion if requested by the client.

Just as it did for the modify form, the script creates the $table variable and prints the delete form (or the error message if no items were found). First, the script outputs the header.

Then it creates the possible delete rows.

Next, if necessary, the script prints an error message.

On the Web, the delete form looks like Figure 13.8.

If asked, the script deletes an item from the database.

The script must be sure that the client actually chose an item to delete with the radio buttons.

First, the script locks the database file as it did for the add item routines.

Then it creates a temporary file as before.

If there is data in the database file, the script checks to see which item matches the deletion.

To do so, the script gets the unique database ID for each database row and chops off the newline.

If the unique database ID of the row is not equal to the database ID number submitted by the client, the script knows not to delete that row. Instead, it prints it to the temporary file.

Once it has gone through all the items in the database, the script copies the temporary file over the database file; the deletion will have been made, because the row that matched the database ID number will not have been printed to the temporary file. Then the script closes the database file and deletes the lock file so that others can modify the database.

Finally, the script prints a standard footer.

The script can also be used to modify an item.

First, the script must be sure that the client chose an item to modify.

As it did before, the script creates the lock file and the temporary file.

And as it did for deletion, the script gets the unique database ID number for each row by popping it out of the @fields array. But this time, it makes sure to add the database ID number into the array so that it will have a whole array again (push (@fields, $item_id)). Finally, as usual, the script chops off the newline.

If the item ID of the database row matches the one that the client submitted, the script renames the @fields array to @old_fields. Otherwise, it adds the line to the growing list of database rows in $new_data.

Once it gets through all the items in the database, the script should have found one that matched the item selected by the client, and the rest should have been stored in $new_data. Now the script prints the rows in $new_data to the temporary file.

Then it prepares to substitute the new data submitted by the client for the old data that was in the database. First, the script initializes a couple of variables: $counter and $new_line. $counter will be used to keep track of the database fields that we have edited, and $new_line will be used to create the new database row.

Now the script begins going through the list of field_values as defined in the setup file.

If the form_data variable associated with that field does not have a value, the script adds the "old" field value stored in @old_fields to the $new_line variable.

On the other hand, if the client submitted new information, the script formats the information as it did for the add routine and adds the resulting value to $new_line.

Then it increments the counter by 1 so that the loop goes through for every field in a database row. Once the loop is finished, the script closes the database.

Next, the script closes everything, copies the temporary file over the original, and releases the lock file.

Then it prints the usual footer.

Again, it is time to sort the entries in the database file so that when people choose day views, their entries are ordered by time. The script creates the lock file so that no one else can modify the database file while we are modifying it.

Then the script adds every row in our database file to the list array @database_fields and creates $comment_row as before.

If the database row is not a comment row (COMMENT:), the script finds the field that has the time of the event and appends it to the front of the database row. It also adds (pushes) the whole string ($sortable_row) into a growing array called @database_rows.

When it has added all the modified rows to the array @database_rows, the script sorts @database_rows.

Next, the script goes through @sorted_temp_database and takes out the extra event_time string at the beginning of each database row.

Then the script creates the temporary file for the modification as it did for the addition.

Next, for each of the database rows stored in @final_sorted_database, the script prints to the temporary file.

Finally, the script copies the temporary file over the original database file so that the resulting file will represent the sort. Then the lock file is removed.

The script adds a default in case clients got through everything without finding what they wanted (probably because they pressed Return when typing into a text box).

The make_month_array subroutine is used to generate the month arrays used by the main routine.

First, the subroutine defines some variables that will be local to this subroutine.

Next, the subroutine defines variables based upon the passed parameter.

Then make_month_array makes a new date based on the first of the month.

make_month_array also gets the weekday of the first of the month and then builds @myarray to be passed to the main routine.

This subroutine checks to see whether the file that we are trying to require exists and is readable by us. This subroutine provides developers with an informative error message when they're attempting to debug the scripts.

First, the @require_files array is defined as a local array and is filled with the filenames sent from the main routine.

The subroutine then checks to see whether the files exist and are readable. If they are, the files are loaded.

If any of the files are not readable or do not exist, the subroutine sends an error message that identifies the problem.

The select_a_month subroutine is used to generate a select list of months that the client can use to select months in the various forms throughout the script. It is a straightforward routine with no new syntax.

As with select_a_month, the select_a_year subroutine generates a select input tag and options for the client to select from a list of years. The only thing of note in this subroutine is that $the_current_year is defined in the setup file and must be changed annually.

The submission_form subroutine is used to generate a form that clients can use to submit new events to the database. As with the previous subroutines, the logic includes no new Perl tricks or syntax.

The header subroutine is used by the main script to generate the HTML header common to every script-generated HTML page.