Quick Setup Instructions
These "Quick Setup" instructions are meant to get you going quickly, without 20 pages of documentation to read!
If you are installing from a Windows machine to a remote server, the process is very simple:
  1. Unzip the downloaded file, making sure that the 'calendarscript' subdirectory is created and contains other files/directories
  2. In the root directory, the 'install.bat' should exist.
  3. Go to a command prompt and run 'install.bat'. It will give instructions on the 4 arguments it requires to run correctly.
  4. An example: install.bat www.yoursite.com username password www/cgi-bin/
  5. This batch file will then use FTP to transfer the files, CHMOD them correctly, create directories, etc.
  6. If there are any problems with this installation and the script does not run, you will need to go through the manual setup process.

If you are an 'expert' user and have a different setup, follow these quick instructions:
  1. Unzip/Un-tar the downloaded file, making sure that the 'calendarscript' subdirectory is created and contains other files/directories.
  2. If you are on a unix machine, make sure you have downloaded the .TAR.GZ file, or use a switch with unzip to make sure all files are converted to ASCII format.
  3. Transfer all files to your web server's CGI directory, with the 'calendarscript' directory in the same location as the calendar.pl and calendar_admin.pl files.
  4. CHMOD 755 calendar.pl, calendar_admin.pl. CHMOD 777 the 'calendarscript' directory and all files/directories under it.
  5. Modify the path to perl in the first line of calendar.pl and calendar_admin.pl, if necessary.
  6. Rename calendar.pl and calendar_admin.pl to calendar.cgi and calendar_admin.cgi if required for your server.
  7. Load calendar_admin.pl in your browser to start the Setup Wizard.
  8. If you get an error message about the BASE_DIR needing to be set manually, un-comment the line near the top of calendar.pl and calendar_admin.pl starting with $BASE_DIR= and set it to be the local file system path of the 'calendarscript' directory (NOT the web server path!).
  9. If you experience any further problems, step through the normal setup documentation and the troubleshooting section.


Before You Begin
Important Questions

Before you begin setup, you must know the correct answers to several questions about your web server environment. If you cannot get the script to run, or you need support in debugging why errors occur, you must find the answers to all these questions. Debugging problems without know the answers to these questions is nearly impossible.

Most users will not need to make any changes to their web server, nor will they need to modify or edit the scripts themselves in any way. However, not every web server and setup is the same, so some people may need to rely on some of this information to get the script functioning in their environment.

Q: Does your web server support CGI scripts?
If the answer is no, you cannot use this program.
Q:In which specific directory, if any, does a CGI script have to be located?
The typical answer is the cgi-bin directory, although some web hosts use a different name and some have no requirement at all for where CGI scripts must be located.
Q: Does your web server support Perl 5?
If the answer is no, you cannot use this program.
Q: What is the full path to Perl5 on the server?
Typically this is /usr/bin/perl, and if you don't know the answer to this you can try it first to see if the default works. If anything fails, you will need to find out the exact answer to this question.
Q: Do perl CGI scripts need an extension of .pl or .cgi?
On most systems, the .pl extension works best. For some, the filenames must be changed to .cgi.
Q: What is the local filesystem path to the directory where the CGI scripts will be located?
This is different than the web path. For example, your scripts might be in /cgi-bin/ on your web server, but on the local hard disk, they might be located in /home/username/web/cgi-bin/ for example. Some web hosts have "virtual" paths for users when they FTP into the web server, so it may be difficult to determine the actual full path to the directory. If this is the case for you, you will need to contact your web host for more information. For most users, this will not need to be known ahead of time. If you encounter a specific error during setup, you will need to know the answer to this question.
Requirements


Installation and Setup
Quick Setup

If you are downloading to a Windows machine, and will then publish the script to your remote web server, the install processes is simplified by using the 'install.bat' batch file.

Download the .zip file to your Windows machine and unzip it. This should automatically create subdirectories containing many files which are needed by the calendar application. In the root of these folders you will find an 'install.bat' file. Go to a command-line and run this program.

To run this install routine, 4 parameters are required: Once this program runs, it will use FTP to login to the server, transfer files, create directories, CHMOD files, etc. If your server doesn't support the CHMOD command or if there are any problems, you will need to follow the detailed install instructions below.


Download

Download either the .zip file or the .tar.gz file from http://www.CalendarScript.com/. The file contents are identical. The .tar.gz file is recommended for people downloading directly to a Unix computer, and the zip file is recommended for everyone else. The .tar.gz file contents are formatted with Unix-style newlines to run in a Unix environment. If you are unsure what any of that means, download the zip file to your local computer.

Uncompress the archive

To uncompress the zip file, using a utility such as Winzip on your local computer and extract the files to an empty directory on your drive. It should automatically create subdirectories containing many files which are needed by the calendar application.

To uncompress the .tar.gz file, use the tar and gzip utilities. It also will create the required directory structure.

Modify Perl Scripts

Two modifications might need to be done to the two perl scripts themselves (calendar.pl, calendar_admin.pl) to function on your server. Whether you need to do these depends on your answers to two questions in the 'Before You Begin' section.

A. Change the path to Perl5
If the path to perl on your web server is not /usr/bin/perl then you will need to open up each of the two files in a text editor and modify the very first line of the files. By default, these lines read:
#!/usr/bin/perl
If you know that your path to perl is different (ex: /usr/local/bin/perl5) then you should change this line to, for example:
#!/usr/local/bin/perl5
This must be the very first line in the file, and the #! are always required.

B. Change the file extensions
If your web server requires perl CGI scripts to have the extension .cgi, for example, then you should rename the two files to the new extension.


Transfer files to the web server

All the files and directories now on your local computer need to be transferred to your web server. The usual method to do this is via FTP. Using FrontPage is not recommended, as it has been known to cause problems with perl CGI scripts.

To FTP the files to your server, connect using a program such as WSFTP or CuteFTP. Navigate to the directory where your CGI perl scripts need to go, and transfer the whole directory structure to this location. Be sure to transfer all files in ASCII mode. If this is not done, file corruption could occur and the program could fail to operate. Once transferred to the web server, you should have calendar.pl and calendar_admin.pl in the CGI directory, and a subdirectory called 'calendarscript' beaneath that directory, containing all the rest of the files. Most good FTP applications will allow you to transfer a whole directory structure at once, automatically creating the necessary directories and putting files into the correct location. If your FTP program does not allow this, consider downloading one that will.


Modify file permissions

Once the files are transferred to the web server, the file permissions need to be modified. This allows for the perl scripts to be executable and for the data files to be writable by the application.

Depending on the operating system of your web server, you may need to take different actions to modify permissions on the files. Also, some web hosts do not allow users to change file permissions themselves. You may need to email your web host and tell them to perform the following permission changes, depending on your setup:

A. For Windows NT/2000 Web Servers
Windows does not require scripts to be set as executable, or write permissions granted via FTP. Instead, permissions on the file system itself must be setup to allow the application to write to the data fies. In Explorer, modify permissions on the 'calendarscript' directory and give 'Full Control' permissions on it and everything in it to 'Everyone'.

B. For Unix/Other Web Servers
File permissions must be set using your FTP program to allow the scripts to be executable and the data files to be writable. If your FTP program or web server does not support the CHMOD commands, see the note above about special web host guidelines.
File permissions must be set as follows:
calendar.pl = CHMOD 755
calendar_admin.pl = CHMOD 755
calendarscript directory and ALL FILES AND DIRECTORIES UNDER IT = CHMOD 777
Knowing how to set permissions on files is a requirement for setting up an CGI script. If these steps don't work or you need more information, search the web for 'ftp chmod' which will bring up many tutorials and sources of more information.

In some situations, web hosts do not allow files in or under the cgi-bin to be chmod 777, for security reasons. These are often situations where the scripts run as your own user ID, not as a user like 'nobody'. If you verify with your web host that this is the case for your site, then you should CHMOD 744 the 'calendarscript' directory and all files under it.


Run the Admin application

At this point, the aplication should be ready to run. To start the setup process, load the calendar.pl file in your web browser. The URL to it might look something like this:
http://www.yourserver.com/cgi-bin/calendar.pl
If the calendar does not display correctly see the next section, "Troubleshooting Installation." If it does display correctly, next check to make sure the calendar_admin.pl application is working. Load it in your web browser. The URL might look something like:
http://www.yourserver.com/cgi-bin/calendar_admin.pl
If the 'Setup Wizard' screen loads successfully, you are all set! You can continue to the Getting Started section. If there are any errors shown or if it doesn't work, please see the next section, "Troubleshooting Installation"


Troubleshooting Installation
If the installation fails or error messages are shown in your browser when you try to load the program, these are some troubleshooting steps you can take to find and correct the problem.

FIRST STEP TO RESOLVE PROBLEMS:
Included with the application is a script named 'debug.pl'. This will be in the same directory as your 'calendar.pl' file. Try to run it via the web browser just like you would run calendar.pl. If there is anything wrong with your installation, such as missing files, incorrct permissions, files not in ASCII format, etc, it will detect the problem and inform you.
If the debug.pl script does not run correctly, see the next solution.
PROBLEM: 500 Internal User Error, or other generic webserver error message

SOLUTION:
1. Verify all the information in the Before You Begin section.
2. Make sure all files were transferred to the web server in ASCII (Text) mode.
3. Verify that the calendar.pl and calendar_admin.pl files are executable.
4. Verify that calendarscript directory exists, and files are located under it.
5. Check the web server's error_log to determine the actual error generated by the script. If you don't know where your error_log is located or how to examine it, contact your web host. This is a critical part of debugging CGI script problems.
6. Make sure everything under the 'calendarscript' directory is writeable, especially the 'session' directory.
7. Contact your web host for further assistance

PROBLEM: Loading the files simply displays the script contents in the browser

SOLUTION:
Your web server is not configured correctly to execute Perl CGI scripts. Try changing the file extension to .cgi if you haven't already. Make sure Perl is installed on the web server and that it is configured correctly.
PROBLEM: Your browser displays the message "Your server does not provide the PATH_TRANSLATED or SCRIPT_FILENAME environment variables. Please see the installation documentation for how to set the $BASE_DIR variable manually."

SOLUTION:
Most web server's provide information to CGI scripts about the directory they are located in. If your server does not, you will receive this message, and you must manually tell the script where to find the files it needs.
First, determine the local filesystem path to the 'calendarscript' directory. More information about this can be found in point 6 of 'Before You Begin'. Next, edit calendar.pl and calendar_admin.pl in a text editor and locate the line the looks like this:
#$BASE_DIR = "/...change.to.full.file.path.of.dir.../calendarscript/";
Remove the first '#' character (this is a Perl comment) and then insert the full path (including starting and ending slash) between the quotes. Save the files and re-upload them to the web server if you are not editing directly on the machine itself. You may need to set the permissions on the files once again.
PROBLEM: Calendar Admin files to load correctly or displays some incorrect output.

SOLUTION:
Verify that all files under the 'calendarscript' directory are world-writable (if Unix) or that that 'Everyone' has 'Change' permissions on the local filesystem (Windows NT).
PROBLEM: Any further errors or problems

SOLUTION:
Contact your web host for detailed assistannce, or post to the Support Forum. Provide all details from the Before You Begin section when posting, along with a DETAILED explanation of the steps you have taken, the output or error mesage you receive, and what you have already done to try to fix the problem.


Getting Started
Basic Concepts

This section will provide a short overview of how the calendar script functions, and how it is designed. Knowing these things will help you to understand some of the functionality of the program, help you to customize it to suit your needs, and possibly help you to debug problems that you might have with the script.

1. Two Separate Applications

CalendarScript consists of two separate applications - calendar.pl and calendar_admin.pl. The first provides the display functionality, and is typically what you will link to on your site. The Admin program is what is used to control calendar settings, add events, change options, etc. The two programs run independently, but share the same files and configuration settings. They are separated in to two applications to reduce the overhead of loading code that you don't need when displaying just the calendar.

2. Multiple Calendars, Single Application

The program allows you to create, configure, and populate multiple calendars with only one instance of the program. That is, you don't need to have separate copies of the script in order to have separate calendars for different office departments, teams, users, or whatever groups you might want to provide a calendar. Each separate calendar has its own events, schedules, and configuration options. Each calendar can be configured to operate in a totally unique way from the others, and contain completely different types of events.

3. Calendars Share Some Options

All calendars in the system share some things. First, users created in the Admin application are global across all calendars. You can give users permissions on specific calendars, but the users themselves do not exist only in a particular calendar. Second, all calendars share the same set of Administrative screens. If you change the colors or design of the Admin application, this will be changed for all calendars which access it.

4. Template-Based Design

The application uses templates to format and display its output. If you are familiar with ASP or JSP files, you will find the format of the templates to be very similar. These templates are plain HTML files that contain special tags and some perl code embedded into the HTML. This allows you as the end-user to completely customize the HTML and change how your screens appear without ever needing to touch a piece of perl code. Of course, if you want to modify the code and structure inside the templates as well as the HTML layout, you can do that as well. When the calendar program runs, it loads the appropriate display template off the disk and formats the output into the template. Therefore, you do not access or run the templates themselves.


Calendar Display Basics

To display your calendar of events on your web site, you will use the calendar.pl program. This program will read the events, process the templates, format the output, and return the result to the browser. So, for example, you might put a link to /cgi-bin/calendar.pl for your main page. You may also embed the calendar output into another page by using Server-Side-Includes, which are covered later in the Advanced Usage section.

The default template that comes with the program has simple navigation and a clean interface. Along the left side are the view and calendar options. Along the top is a navigation bar to change the date ranges displayed in the calendar. It changes depending on which type of view you are currently in. Below it is the actual output of events and days, depending on your view options.

1. Display Options 2. Calendar Functions 3. Navigation

Navigating between months, weeks, days, etc is very simple. Along the top of the display will always be a navigation bar, customized for your current view. In the monthly view, for example, you see a list of all 12 months with the currently-displayed month highlighted. You can instantly jump to any month in the current year, or navigate to the next or previous year using the links on the left and right of the navigation bar.

When in any view other than a day view, you can click on either the date in a box (in Grid mode) or the day header (in List mode) to jump to a view of that day only.

4. Event Details

By default, only a summary of each event is shown on the calendar view. To view more details about an event, you can either click on the "details" link (if in Daily view) or the title itself (in any other view).

The event details will show all the data for the event, including all custom fields that may have been configured using the Admin interface.

5. Displaying calendars other than the default

This application is built to support multiple separate calendars, all from the same program. When the calendar.pl program is loaded, it displays the default calendar, which can be selected in the Admin interface. If you wish to display a different calendar, however, you must provide the calendar ID in the URL. For example, to load a calendar with ID "vacations" you would load:
/cgi-bin/calendar.pl?calendar=vacations
This is just an example. Your calendar will have its own ID to replace 'vacations' in the example above, and the path to calendar.pl might be different on your server.


Calendar Admin Basics

The Calendar Admin program is used to configure the calendar display and to make any changes to events, schedules, users, permissions, etc.

1. Logging In

After setup, the Calendar Admin program has only one user ID configured. The login name is 'Administrator' with no password. All usernames in the program ARE CASE-SENSITIVE. When you first login to the program, do so as Administrator. You will be prompted to create a new password which will be used from then forward for the Administrator account.

After successfully logging in, you are forced to pick which calendar you will be editing. All configuration changes and event changes will be done on the calendar you select. You can switch the calendar context by selecting the "Change Calendar" option.

2. Drop-down Navigation

The main menu of the Calendar Admin program has a list of all options that you can perform on the currently-selected calendar. Depending on the permissions granted to your user ID, you will see different options on the main screen.

To navigate between screens in the Calendar Admin application, use the drop-down menu at the top of screen. This menu also displays only the options which are available to the user ID you are logged in as.

3. Adding an Event

To add an event, login as Administrator, or a user that has the 'Add Event' permission. Select 'Add Event' from either the Main Menu or the drop-down navigation menu. This will take you to the Add Event screen.

This screen is where you will enter the details for the event. In this program, events are separate from their schedule. This makes it possible to have an event added which has no schedule at all, or have an event which has multiple independent schedules. The first screen is for entering the details regarding the event itself, which is independent from the schedule.

When finished entering the information for the event, click 'Save and Continue' to proceed to the Schedule Event screen. This screen allows you to select the time and date(s) when the event will occur. In order to schedule a recurring schedule (such as every Monday of the week, for example) click on the 'Recurring Schedule' button. This screen allows you to specify a more complex schedule for the event. To switch back to the previous screen, click the 'Standard Schedule Options' button. When finished scheduling the event, click 'Save.'

For details about the Schedule Event screens and what each option means, refer to the Administration Application section for this screen.

4. Changing Calendar Options

There are a number of options which can be configured for each calendar in the system. These include such things as the date display format, day and month names, allowing HTML formatting, etc.

To change these options, login as Administrator and navigate to the 'Current Calendar Settings' screen. There you will find a complete list of options.

5. Creating a User

Multiple users can be created and used within the calendar program, each with their own security permissions. By default, two users exist: Administrator and anonymous, neither of which can be deleted. The Administrator account has full privileges to every calendar and is used to create other accounts and setup security permissions. The anonymous account has no permissions by default and must be given privileges to perform any action. This account is used to allow the public to add events to a calendar, for example, without logging in.

To create a new user, login as Administrator and navigate to the 'Add User' screen. Enter a new user ID (case-sensitive), a password, and a display name for the user. To save your new user and continue to the 'Permissions' screen for this user, leave the 'Edit permissions for this user' checkbox checked. If you wish to add the user and not edit the security privileges at this time, uncheck the box.

6. Assigning Permissions

By default, a new user has no permissions to do anything to any calendar in the system. You must explicitly grant permissions per action, per user, per calendar.

The Permissions screen consists of a number of checkboxes. Each box that is checked indicates that this permission is enabled for this user.

The options are divided into two sections: Global Permissions and Specific Permissions. The 'Global Permissions' section displays security permissions which are not specific to any one calendar, but affect the Calendar Admin application itself or options which affect all calendars in the system. The 'Specific Permissions' section has three columns to enable permissions for the specific user for the current calendar only, or for all users in the current calendar, or for all calendars for the current user. For more specific information about the Permissions screen, see the Administration Application section for this screen.


Administration Application
This section details each screen in the Administration Application.

Login Screens

Login

The Login screen is displayed when entering the Calendar Admin application. All user ID's are case-sensitive. When logging out of the Admin Application, there is also a 'View Calendar' link to the calendar that you were just editing.

Your user ID must have permissions to perform at least one operation on at least one calendar to login to the Calendar Admin application.

Select Calendar

The Select Calendar screen is displayed after a user logs in successfully. This selects the 'context' that the Calendar Admin application operate under. All calendar-specific operations will affect this calendar. You can change which calendar is being modifed at any time by choosing the 'Change Calendar' link from the menu.

The list of calendars will only include those that your user ID has permission to operate on.

Main Menu

The Main screen includes links to all the functions of the Calendar Admin application. Only actions which your user ID has permission to perform are included in the list.


Events

Add Event

To add an event, enter values for all fields in the Add Event screen. These fields and their input types are configured via the Customize Event Fields screen. Click 'Save And Continue' to save the event and continue to the 'Schedule Event' screen.

Schedule Event

The Schedule Event screen handles scheduling an event's time, date, and recurring schedule. It is the screen with the most number of options and can therefore be confusing at first glance. However, using it is common sense.

There are two modes of the Schedule Event screen - Static Schedule and Recurring Schedule. The Static screen allows you to schedule an event on any number of individual days, or on every day in a date range (between two dates). The Recurring screen allows you to schedule an event that repeats on a regular basis. To switch between these two modes, click the 'Recurring Schedule' button on the Static screen, or the 'Standard Schedule Options' button on the Recurring screen.

Event Time (common to both screens)
Events are either sceduled as 'All Day', meaning they have no start and end times during the day (used for Holidays, for example), or given a start time and optionally an end time.

To schedule an All Day event, click the All Day checkbox. This will clear any values that might have existed in the time entry fields. This event will be displayed in the calendar without any time next to it.

To set the time for an event, enter the values into the input fields. The time input fields can be configured as either 12-hour format, using AM/PM, or 24-hour format. This is a setting in the Calendar Admin application. If a start time is entered and no end time is entered, the end time is automatically set to be the same time as the start time. This is an indication to the calendar program that this event has no specified end time. In the calendar display, this will be shown as the event occurring at the specified time but without a time range.

The end time must always be after the start time. Also, the two times must occur on the same day. That is, you cannot schedule an event to start at 11:00pm and end at 2:00am the next day. This type of schedule is currently not supported.

Static Date Entry
There are two options for schedule a date on the static screen. You may either select individual dates when this event will occur, or a date range during which the event will occur every day. By default, Individual Dates is selected.

Dates may be entered into the text box by hand, or the popup calendar may be used to select dates. If entering dates manually, separate them by commas and use the format specified above the input boxes. This date format is a setting in the configuration of the calendar and may be changed in the Calendar Admin application. To use the popup calendar utility, click on the '>' button. This will open a small new window containing a calendar. Click on the dates on which this event will occur. After clicking a date, the calendar will re-draw with the selected date having a yellow background. You can click on the date again to un-select that date. You can easily select today's date by clicking the 'Today' link at the bottom. To close the window, either cloes the browser window manually, or click anywhere on the main Schedule Event screen to close it automatically.

To enter a date range for the event, enter begin and end dates in the format specified above. You may use the popup calendar utility to select either of these dates also. The dates selected are inclusive, meaning the event will occur on the starting and ending dates as well as all dates between.

Recurring Schedule Entry
A recurring event can either repeat forever or repeat only during a given date range. If the 'Repeat only between these dates' option is checked, you must supply a Start and End date. The event will only repeat on matching dates between these two dates (including on the dates themselves). Without this option checked, the event will appear with the repeating schedule forever, on any calendar year/month viewed.

It is always recommended to supply a Start and End date for events, for performance reasons. A number of recurring events which have no Start and End dates may cause the calendar to slow down, because the schedules of these events need to be re-calculated with every request. It is always recommended that you put in a date range for recurring events, and this option is selected by default.

There are a number of options available for a recurring event schedule. Changing any option will automatically select the corresponding Weekly/Monthly/Yearly option and sub-option, if it applies.

Edit/Delete Events

The Edit/Delete Events screen displays events and their schedules so you can Edit, Delete, or Reschedule them. By default, the screen displays all events for the current month. You can view events occurring in other months by using the drop-down menus for month and year and then clicking 'Go', or by using the << and >> links to go back or forward one month. You can also do a simple search for events by entering a word into the text field and clicking 'Search'. This search matches the text in any field of the event and cannot be restricted to only certain fields.

When events for the month are being displayed, every start date and time during the month is displayed, as well as the title. An asterisk is displayed to signify that the event has a recurring schedule.

When search results are displayed, the ID of the event (as stored in the database), the date of the next occurrence, and the event title are shown.

Clicking the 'Delete' button for any event will delete it from the database, after accepting the confirmation dialog box.

Clicking 'Edit' takes you to the Edit Event screen, where you can change the details of the event. From this screen you can also navigation to the Schedule Event screen to modify its schedule, or uncheck the 'Modify event schedule now' checkbox to return to the Edit/Delete Events screen without rescheduling the event. Click 'Schedule' to change the schedule of the event.

When deleting, editing, or rescheduling recurring events, all occurrences of the event will be changed. Changing only one instance of a recurring event is currently not supported.

Customize Event Fields

The 'Customize Event Fields' screen lets you modifying the data fields that define an event. There are a number of fields pre-defined, some of which are not editable, and others which can cannot be deleted and only partially edited.

To add a new field, click the 'Add New Field' button at the top of the screen. To edit or delete an existing field, click the Edit or Delete button next to the field. Adding or Editing a field takes you to the Add/Edit Field screen.

At the bottom of the screen you can change the display order of the fields. This affects the order that they are displayed in for the event details screen as well as the Add Event screen. To move an option up or down, highlight it and click the 'Up' or 'Down' button. To save the changes, click the 'Save Order' button.

Add/Edit Field

This screen defines a field for either the event database or the user database definitions. When you are finished defining the field, click 'Save' to update the database and instantly activate the field.

Approve Pending Events

If a user (such as the anonymous user) has privileges to add an event, but not automatically approve their own events, then any events they add will be added to a 'pending' list. A user with the 'Approve Pending Events' privilege can then login to approve the events and make them active.

Each event is shown with its Title, Description, Author, ID, and Schedule. To the left is the options of 'No Action', 'Approve' or 'Reject'. Select the action for each event in the list and click 'Save' to save all of them. Anything approved or rejected will be removed from the list, and the others will remain in the pending list.

To edit an event before approving it, click the Edit button. This will take you to the Edit Event screen and also allow you to proceed to the Schedule Event screen. Once finished editing and saving the event, you will automatically be returned to the Approve Pending Events screen.

Import Events

The Import Events screen allows you to load a number of events, their details, and their schedules all in one step. It is useful for upgrading from a previous version of the program, or for loading events from another application.

The format of events to import must be in a delimited text file. That is, each part of the event's details and schedule are separate by a character such as | or comma. To import the contents of this file, you need to provide the following 4 things:
  1. The format row. This is a row that defines which fields appear in which order in your file. This is required so that the fields can be imported and mapped to the correct fields in the CalendarScript application. It may or may have a # as the first character, and should contain fields names separated by the delimiter.
  2. The text of the file. This just consists of a number of lines, one for each event. The lines should be separated by the delimiter and have the value for each field in the same order as the header row.
  3. The delimiter used to separate fields, both in the header row and the text
  4. Field Mappings. This is a list of all the event fields which you have defined in your calendar, as well as schedule fields. When you change the format row at the top, this will populate the drop-down boxes next to your event fields. Then pick which field from the import file should be mapped to which field in the CalendarScript database. The date field is required, but the times are optional. Iif time fields are not mapped, then each imported event will become an 'all day' event.

Once this is complete, click 'Import' and all the events will be loaded into the database.


User Admin

Change Your Password

Every user except the anonymous user has the ability to change their password. simply type in the old password and the new password twice and save.

Add User

Add user enables you to create additional users for the calendar application, and then assign privileges to that ID.

The fields available to fill in by default are Username, Password, and Name, which are all required. You may add additional fields and customize these fields through the Customize User Database screen.

If the 'Edit permissions for this user' box is checked, you will be taken to the permissions screen for this user once it is added to the database.

Edit/Delete Users

This screen lists all current users in the system, and allows you to edit and delete users. The 'Administrator' and 'anonymous' users may not be deleted.

Clicking on the 'Edit' button will take you to the Edit User screen, which is identical to the Add User screen. The Username field may not be changed, but all others may. If you wish to change the Username of a user, you must delete their user and add a new one.

Modify User Permissions

There are a number of specific permissions that may be granted to users of the system to enable them to perform these actions of the Calendar Admin application. This screens allows you to grant those permissions to users.

When the screen first comes up, it has a list of calendars and users on the system. Select a calendar, then select a user whose permissions you wish to edit. Click 'View Permissions' to load all the current permissions for that user.

Permissions may not be change for 'Administrator' because this account always has full permissions on all calendars in the system. The 'Anonymous User' account is used for anyone viewing the calendar without logging in. So, in order for the 'Add Event' link to appear on the calendar for the general public, for example, you will need to grant the 'Add Event' permission to 'Anonymous User'.

The list of permissions is divided into two categories - Global Permissions and Specific Permissions. The Global Permission section grants permission to access screens and functions of the Calendar Admin application which are common among all calendars. These options are as follows: The second set of permissions are the 'Specific Permissions'. These allow you to grant permissions to a specific user for a specific calendar, or for all users for a specific calendar, or for any calendar for a specific user. These separate categories are divided into three columns, and each individual permission exists in each column.

A user has permissions to perform a given action if a check appears in any of the three columns. For example, the 'Add event' permission might be checked in the second column, meaning all users for this calendar are able to perform this action. No matter which user you view permissions for, this will always be checked, meaning the user will be able to perform this action.

These three different levels of granting permissions allow the Administrator to easily give everyone access to some functions, yet restrict other actions to only specific users. It also allows a user to have the 'Add Event' permission on every calendar in the system, but only be able to change settings on one of the calendars, for example. The different permissions are as follows: Customize User Database

This screen functions the same as the 'Customize Event Fields' screen, except that it modifies the fields that exist for a user in the system.


Calendar Options

Current Calendar Settings

This is where all the configuration otions for a calendar can be customized. The options on this screen only apply to the currently-selected calendar.
Global Options

Manage Calendars

The calendar program allows you to create multiple calendars all run through the same script, and this is the screen to add, edit, and delete those calendars. The main screen contains the list of calendars, and the Edit/Delete buttons. Whichever calendar is currently selected as the 'Default Calendar' in the Admin Interface screen cannot be deleted.

To add a new calendar to the system, click the 'Add Calendar' button. This brings up the screen to add the details for the calendar. Admin Interface

This screen allows you select several high-level options, and customize the colors of the Calendar Admin screens. Feedback/Support

This screen provides a number of options for obtaining support information, providing feedback, and checking for updates.


Customization
Modifying Display Templates

Template Introduction

The output of the calendar display is extremely flexible and easily changable through the use of templates. These templates define how the data should be displayed, and consist of plain HTML, some special calendar-specific tags, and possibly some actual Perl code. By modifying these templates, you can make the calendar display fit into your site design and/or completely change the design of the output. There are almost no limits, and the true power of this program lies in the fact that you can make it do almost anything.

Modifying existing templates will most likely be very simple for anyone familiar with HTML. You can add a header, change colors, add graphics, or whatever you wish simply by editing an existing template style and changing the HTML. To do more advanced changes and customization, you will need to familiarize yourself with the special calendar tags designed for use in the calendar templates. To get full control over the templates and make the most radical and advanced changes, you will need to be familiar with the Perl programming language.

The display template files themselves are located under the 'calendarscript/templates/calendars' directory. A template set may consist of any number of files, or possibly just a single file. Each different template design is stored as its own directory, with the template files themselves in the directory. This directory name is what will show up in the 'Current Calendar Settings' screen when choosing which template style to use for any given calendar.

When the calendar program is called by your web browser, it processes the request and loads the appropriate template file. The template files is parsed, values are filled in, and then the output is sent back to the browser to be displayed. Therefore, the templates aren't actually called by themselves, but instead are used internally in the program.

If the calendar is not specifically told which template to load, it will try to load the file called 'default.html' in the defined template directory. The output of this template can then link back to other templates to be displayed. You could then have different ways of displaying the calendar data (month, week, day, grid, list, etc) each have their own template file, and the template files would link to each other.

Template Processing Flow

The following is an explanation of the steps that the program goes through when processing a template to display.
  1. Load the template file. If there is an error or the template doesn't exist, an error will be shown to the screen.
  2. Load all include files and insert them into the template, if applicable.
  3. Remove all comments from the output, in the format <!-- comment -->
  4. Replace all calendar-specific tags with the Perl translation
  5. Convert all plain text/HTML into Perl "print" statements.
  6. Do an eval() of the resulting code (run it) and capture the output.
  7. In the case of an error processing the resulting code, display the original and converted template to the browser for debugging.
  8. In the case of a successful execution, display the output to the browser.
Template Example

Below is an example of a very simple display template. It will display a typical monthly calendar grid, with the title of each event in the grid, and links to the next and previous months. Note the special syntax and tags embedded in the HTML to generate the display.
<%
&getEvents( { 'range'=>'month' } );
%>
<HTML>
<HEAD><TITLE>Calendar</TITLE></HEAD>
<BODY>
<CENTER>
<TABLE BORDER=1>
<TR>
   <TD ALIGN="center" COLSPAN="<%=$Grid->{'colcount'}%>">
      <A HREF="<%=$CGI_URL_QUERYSTRING%>month=<%=$LAST_MONTH%>&year=<%=$LAST_MONTH_YEAR%>">&lt;&lt; <%=$LAST_MONTH_NAME%></A>
      &nbsp;&nbsp;&nbsp;
      <FONT SIZE="+3"><%= $MONTH_NAME %> <%= $YEAR %></FONT>
      &nbsp;&nbsp;&nbsp;
      <A HREF="<%=$CGI_URL_QUERYSTRING%>month=<%=$NEXT_MONTH%>&year=<%=$NEXT_MONTH_YEAR%>"><%=$NEXT_MONTH_NAME%> &gt;&gt;</A>
   </TD>
</TR>
<TR>
<%FOREACH GRID COLUMN%>
   <TH><%= $Grid->{'daynames'}->[$COL] %></TH>
<%/FOREACH%>
</TR>
<%FOREACH GRID ROW%>
<TR>
   <%FOREACH GRID COLUMN%>
   <TD VALIGN=TOP WIDTH="14%">
      <%IF DISPLAY%>
         <B><%=$DAY->{'dd'}%></B><BR>
         <%FOREACH EVENT%>
            <FONT FACE="arial" SIZE="-2">&#149; <%= $EVENT->{'details'}->{'title'} %></FONT><BR>
         <%/FOREACH%>
      <%/IF%>
   &nbsp;</TD>
   <%/FOREACH%>
</TR>
<%/FOREACH%>
</TABLE>
</CENTER>
</BODY>
</HTML>
Tag Syntax

The templating system in this application is designed to look and function in a way that is similar to ASP and JSP. This way, it will look familiar to anyone familiar with those common web technologies and will also appear correctly syntax-highlighted in editors such as Homesite, which understand ASP/JSP.

This templating system introduces two new forms of syntax for tags.

1. <%= VALUE %>

This tag format displays a value to the screen. Anything between the <%= and %> tags is evaluated and its value is displayed in output. These are some examples of output expression tags and their display values:
<%= (3+4) %> = 7
<%= $DAY %> = The value of the $DAY variable
<%= &func() %> = The output of the Perl subroutine called 'func'
The contents of the <%= %> tag are fed directly into Perl's "print" statement. So, a statement like this: <%= (3+4) %> becomes this after the template is parsed: print (3+4); Keep this in mind when creating your templates so as not to create syntax errors.

2. <% CODE %>

This tag contains Perl code, or pre-defined special tags which get translated into Perl code. Any Perl code embedded inside these tags will be executed like normal.

This is a small example of a block of template text and an explanation:
<% foreach $i (0 .. 10) { %>
<%= $i %><BR>
<% } %>
The text between the <% %> tags is standard Perl code that counts from 0 to 10 and puts the value into the $i variable. Then the <%= $i %> outputs the current value of $i for each time through the loop and appends a "<BR>" at the end for a new line. When the template parser processes this junk of code, it would turn it into exactly this Perl code:
foreach $i (0 .. 10) {
print $i; print "<BR>";
}
When executed by eval() this code would function just as it would if put into a Perl script by itself and print the expected output.

Special Calendar Tags

A number of tags are supported in the calendar templates which are specific to the calendar application. These special tags are translated into perl before the rest of the template is executed.

An example is this tag: <% NEXT MONTH LINK %>

By itself, this would generate an error, because the text "NEXT MONTH LINK" is not valid Perl code, and would cause a syntax error. However, this special tag is replace with valid (and somewhat complex) Perl code to generate a link to the next month of the calendar display. These special tags or provided to simply the templates, and make it easier to customize without having to learn the internal operations of the calendar.

Many of the special calendar tags are used to loop through days or events, or to decide whether certain things should be displayed. These have very easy syntax, so looping through days or events and deciding what to show is easy. This is an example of a simple loop/conditional blocks:
<% IF EVENTS EXIST %>
   <UL>
   <% FOREACH EVENTLIST %>
      <LI><%= EVENT FIELD(title) %>
   <% /FOREACH %>
   </UL>
<% ELSE %>
   No events Exist
<% /IF %>
In this example, the "IF" tag here is used to determine if there are any events to display. If there are, it loops through each event and displays the event's title in a bulleted list. If there are no events, it displays the "No Events Exist" text.

For a complete list of special tags and their meanings, see the Template Reference section later.

Defined Variables

There are a number of Perl variables defined in the calendar templates which do not have their own special tags. These variables are, by convention, all uppercase. You can reference these variable values just as you would any other Perl variable in your template, either in a display tag or in a code tag.

An example of this is $TODAY_MONTH, which holds the month number of today's date. There is no special tag to display this, but inserting <%= $TODAY_MONTH %> in your template will display its value. You can also reference in perl code such as <% if ($TODAY_MONTH > 6) %>. The full list of defined variables is available in the Template Reference section.

Include Files

Other files can be included into a template, much like Server-Side-Includes on a typical web server. Since the templates are not actually processed by the web server, but by the calendar program instead, the include commands do not function exactly as SSI's do. However, the syntax is similar in order to be familiar to those who use SSI's.

The syntax to include another file is:
<!--#include file="filename.html"-->
All file paths are relative to the template directory, so including a file like "header.html" will look for the file in the same directory as the file that is including it. You can use ../ relative paths to go up a directory.

Included files can be named anything, and have any extension - they do not need to be called .html files. Included files may contain Perl code that will be inserted into the template just as if it was there to begin with. Included files may not, however, include other files. If an include statement is contained in an included file, it will simply be ignored.

Retrieving Events

When creating a display template, and obvious task it must perform is to load the events that it will display. Events and their schedules are not loaded by default - it is up to the template to decide which range of events it wishes to load. This is because each template may be displaying a different date range, or a diferent type of event. It should know which events it needs to retrieve. Once the call is made to load the events, the calendar program retrieves them, stores them into special variables, inserts them into a grid in the proper places, and prepares special tags to be available in the rest of your template.

The call to retrieve events is done via the getEvents() subroutine defined in the calendar program. This call should be placed at the top of your template (assuming the output of the particular template contains events). An example call to load events is:
<% &getEvents( { 'range'=>'month' } ); %>
This loads all events and their schedules contained in a certain month (the range). By default, the getEvents() call will use dates relative to those currently selected. That is, if January 2001 is currently being displayed, and you click a link to go to the next month, the above line will get events for February 2001. You can of course over-ride this behavior and retrieve events for a specific year, month, date, or range if you wish.

The call to retrieve events is a standard Perl subroutine which takes an associative array of values as its argument. The general format is:
&getEvents({ name1=>value1 , name2=>value2 , name3=>value3 });
For a list of all possible arguments to this function and what effect they have on the events being retrieved, see the Template Reference section.

Retrieving A Single Event

Like the getEvent() function to retrieve a list of events, there is also a function to retrieve a single event. This is useful for a screen which displays the details of an event, for example. The format of this call is:
<% &getEvent( event_id ); %>
Template Debugging

If a template contains an error - usually invalid Perl code between <% %> tags - then an error screen will be displayed with debugging information. The actual error reported by Perl will be shown, followed by the original template, then the Perl code generated by the template after parsing. The line where Perl reported the error will be highlighted in yellow, and a link to the line is provided at the top in the actual Perl error message reported.

Occasionally, due to how Perl locates the source of an error, the actual line causing the problem may be a little above or below the highlighted line.

Advanced Notes

For template designers who are familiar with Perl, here are some additional noted which may be useful:
Template Reference

Template Tags

These are special tags that are specific to the calendar display, and have special meaning.

<% code %> Evaluate Perl code
<%= expression %> Print out the value of expression
<% CALENDAR NAME %> The name of the currently-displayed calendar
<% CALENDAR KEY %> The key of the currently-displayed calendar (to be used for linking, etc)
<% CALENDAR DESCRIPTION %> The description of the currently-displayed calendar
<% FOREACH GRID ROW %> ... <% /FOREACH %> Loops through each available row in the grid of dates, setting the variable $ROW to the row number, beginning with 0
<% FOREACH GRID COLUMN %> ... <% /FOREACH %> Used inside of the "FOREACH GRID ROW" tag, this loops through each column available in each row, beginning with 0. It sets the value of the $DAY variable to be a reference to the day in the current Grid Row/Col, and sets the $EVENTS variable to be a reference to that day's events
<% FOREACH HOUR OF DAY %> ... <% /FOREACH %> Loops through the hours of the day, so you can pull out events by hour. The first 'hour' returned is '99' which is code for 'All Day Events'. The first and last hours of the day that are returned are specified in the config file as 'days_hours_display_start' and 'days_hours_display_end' but there is no interface in the Calendar Admin to change them - they must be changed by hand. This loop works on the current $DAY reference, so this must be used in a context where $DAY is defined. Inside the loop, the $EVENTS variable is set to be a reference to the list of events for that hour of that day.
<% FOREACH EVENTLIST %> ... <% /FOREACH %> Loops through each day existing in the current view without respect to the grid. It sets the $DAY variable to be a reference to the day, and the $EVENTS variable to be a reference to the events for that day.
<% FOREACH EVENT %> ... <% /FOREACH %> Loops through each event in the current list of events held in the $EVENTS variable, setting the $EVENT variable to be a reference to each event.
<% FOREACH SEARCH RESULT %> ... <% /FOREACH %> Loops through each event that exists in the search results, if a search was done. It sets the $EVENT variable to be a reference to each event in the results.
<% IF SEARCH RESULT %> ... <% /IF %> Evaluates the block if a search was just executed.
<% IF SEARCH RESULTS EXIST %> ... <% /IF %> Evaluates the block if at least one search result is returned as a result of a search.
<% IF EVENTS EXIST %> ... <% /IF %> Evaluates the block if the current $EVENTS variable contains at least one event.
<% IF NO EVENTS EXIST %> ... <% /IF %> Evaluates the block if the current $EVENTS variable does not contain any events.
<% IF NEXT OCCURRENCE EXISTS %> ... <% /IF %> Evaluates the block if the current event held in the $EVENT variable is set to occur any time in the future.
<% IF DISPLAY %> ... <% /IF %> Evaluates the block if the $DAY variable contains a reference to a day which should be displayed. In a Grid display, for example, some of the grids do not contain actual dates, so you should not attempt to display the date number in that grid cell.
<% IF SELECTED %> ... <% /IF %> Evaluates the block if the current day in the $DAY variable is selected as the date to highlight or show in detail.
<% IF USER LOGGED ID %> ... <% /IF %> Evaluates the block if the current user is logged into the calendar.
<% IF ... %> block1 <% ELSE %> block2 <% /IF %> The ELSE tag is used in conjunction with the above conditional tags to define a block to evaluate if the condition is not true.
<%= EVENT FIELD(name) %> Outputs the value of the 'name' field in the event currently defined in the $EVENT variable. For example, 'title', or any other field defined in the Customize Event Fields screen.
<%= SCHEDULE FIELD(type) %> Outputs a part of the schedule for the current occurrence of the current event held in $EVENT. The following values are available for the value of 'type':
  • start = gmtime() value of when the event occurrence starts.
  • end = gmtime() value of when the event ends
  • year = 4-digit year
  • month = The month number, from 1-12
  • date = The day of the month
  • day = The day number, from 0-6
  • datestring = The date in format yyyymmdd
  • start_ss = The seconds value of the start time, 0-59
  • start_mi = The minutes value of the start time, 0-59
  • start_hh = The hours value of the start time, 0-23
  • start_time = Formatted string of the start time, according to 12/24-hour format preference in config file
  • end_ss = The seconds value of the end time, 0-59
  • end_mi = The minutes value of the end time, 0-59
  • end_hh = The hours value of the end time, 0-23
  • all_day = 1 if this is an all day event, otherwise blank or 0
<% LAST YEAR LINK %> , <% NEXT YEAR LINK %> The URL to navigate to the previous or next year.
<% LAST MONTH LINK %> , <% NEXT MONTH LINK %> The URL to navigate to the previous or next month.
<% LAST WEEK LINK %> , <% NEXT WEEK LINK %> The URL to navigate to the previous or next week.
<% PREVIOUS DAY LINK %> , <% NEXT DAY LINK %> The URL to navigate to the previous or next day.


Template Variables

These are Perl variables available in your templates. You can use these inside of <% %> code blocks, or print their value using <%= $VARIABLE %>.

$Config A reference to a Config object for the calendar. You can retrieve values from the config file for this calendar by using the syntax $Config->get("aCODEribute_name").
$AdminConfig A reference to the Admin config file and functions the same way.
$Session A reference to a CGISession object, to retrieve or set values in the user's session. This will only apply if the user is logged in. It is most useful in the Admin templates.
$CGI_URL The URL of the calendar application, so you can link back to it or submit forms back to it.
$CGI_URL_QUERYSTRING The URL of the calendar application, but with all current display parameters aCODEached to the end of it. This should be used rather than $CGI_URL in most cases where you are making a link.
$QUERY_STRING The current display parameters in a URL-encoded query string.
$CGI_HIDDEN_FIELDS The current display parameters in HTML hidden fields. If you create a form that submits back to the CGI URL, include these hidden fields.
$ADMIN_CGI_URL The URL of the Calendar Admin application.
$User A reference to the User object of the user currently logged in. Fields in the user database can be accessed using $User->{fieldname}. You can also use $User->isCalendarAdmin(calendar_id) to determine if the user has any Admin permissions on the calendar with id "calendar_id".
$userMessage The text of any message that should be displayed for the user.
$YEAR_SELECT Contains the text of an HTML SELECT element containing a list of options for each year. If you have a form and want the user to select a year, simply output the value of this variable.
$MONTH_SELECT Contains the text of an HTML SELECT element containing a list of options for each month's full name. If you have a form and want the user to select a month, simply output the value of this variable.
$MONTH_ABBREVIATION_SELECT Contains the text of an HTML SELECT element containing a list of options for each month's abbreviation. If you have a form and want the user to select a month, simply output the value of this variable.
$DAY_NAMES A reference to an array of the names of days of the week. The name of the first day of the week would be $DAY_NAMES->[0].
$DAY_ABBREVIATIONS A reference to an array of the abbreviations of days of the week. The abbreviation of the first day of the week would be $DAY_ABBREVIATIONS->[0].
$MONTH_NAMES A reference to an array of the names of the months. The name of the first month would be $MONTH_NAMES->[0].
$MONTH_ABBREVIATIONS A reference to an array of the abbreviations of months. The abbreviation of the first month would be $MONTH_ABBREVIATIONS->[0].
$DAY_NAME_0 .. $DAY_NAME_6 Separate variables for the names of each day, 7 variables in all.
$DAY_ABBREVIATION_0 .. $DAY_ABBREVIATION_6 Separate variables for the abbreviations of each day, 7 variables in all.
$MONTH_NAME_0 .. $MONTH_NAME_11 Separate variables for the names of each month, 12 variables in all.
$MONTH_ABBREVIATION_0 .. $MONTH_ABBREVIATION_11 Separate variables for the abbreviations of each month, 12 variables in all.
$YEAR The 4-digit year of the currently displayed date.
$MONTH The month number of the currently displayed date.
$MONTH_NAME The month name of the currently displayed date.
$DATE The date of the currently displayed date.
$DATESTRING The yyyymmdd date string of the currently displayed date.
$LAST_YEAR The 4-digit year of the previous year from the one currently displayed.
$NEXT_YEAR The 4-digit year of the next year from the one currently displayed.
$LAST_MONTH_YEAR The 4-digit year of the previous month from the one currently displayed. If the current month is January, for example, this will be the previous year. Otherwise it will be the same year as the current.
$NEXT_MONTH_YEAR The 4-digit year of the next month from the one currently displayed. If the current month is December, for example, this will be the next year. Otherwise it will be the same year as the current.
$LAST_MONTH, $NEXT_MONTH The number of the previous month and next month from the one currently displayed.
$NEXT_MONTH_NAME, $LAST_MONTH_NAME The names of the previous month and next month from the one currently displayed.
$LAST_WEEK_YEAR, $LAST_WEEK_MONTH, $LAST_WEEK_DATE The year, month, and date of the week prior to the currently-displayed date.
$NEXT_WEEK_YEAR, $NEXT_WEEK_MONTH, $NEXT_WEEK_DATE The year, month, and date of the week after the currently-displayed date.
$PREVIOUS_DAY_YEAR, $PREVIOUS_DAY_MONTH, $PREVIOUS_DAY_DATE, $PREVIOUS_DAY_DATESTRING The year, month, date, and yyyymmdd date string of the date prior to the one currently displayed.
$NEXT_DAY_YEAR, $NEXT_DAY_MONTH, $NEXT_DAY_DATE, $NEXT_DAY_DATESTRING The year, month, date, and yyyymmdd date string of the date after the one currently displayed.
$TODAY_YEAR, $TODAY_MONTH, $TODAY_DATE, $TODAY_DATESTRING The year, month, date, and yyyymmdd date string of today's date, regardless of which date is currently being displayed.
$CALENDAR An object containing the properties of the currently-displayed calendar.
$RANGE_START A formatted date string (formatted according to config settings) representing the first date in the range currently being displayed.
$RANGE_START_YEAR, $RANGE_START_MONTH, $RANGE_START_DATE The year, month, and date of the first date in the range currently being displayed.
$RANGE_END A formatted date string (formatted according to config settings) representing the first date in the range currently being displayed.
$RANGE_END_YEAR, $RANGE_END_MONTH, $RANGE_END_DATE The year, month, and date of the last date in the range currently being displayed.
$EVENTS A reference to a list of $EVENT objects for every event displayed in the current view.
$GRID_ROW_COUNT, $GRID_COL_COUNT The number of rows and columns in the grid required to display all the dates in the current view.
$Grid
$Grid->{rowcount}
$Grid->{colcount}
$Grid->{grid}->[y]->[x]->{dd}
$Grid->{grid}->[y]->[x]->{mm}
$Grid->{grid}->[y]->[x]->{yyyy}
$Grid->{grid}->[y]->[x]->{d}
$Grid->{grid}->[y]->[x]->{yd}
$Grid->{grid}->[y]->[x]->{dayname}
$Grid->{grid}->[y]->[x]->{dayabbreviation}
$Grid->{grid}->[y]->[x]->{monthname}
$Grid->{grid}->[y]->[x]->{monthabbreviation}
$Grid->{grid}->[y]->[x]->{datestring}
$Grid->{grid}->[y]->[x]->{display}
$Grid->{grid}->[y]->[x]->{selected}
$Grid->{grid}->[y]->[x]->{events}
$Grid->{grid}->[y]->[x]->{hours}->[hh]->{events}
$Grid is a reference to an object containing all the details of the grid required to display all the dates in the view. Each cell in the grid can be referenced by column and row, to retrieve the date details of that grid cell and the events that should be displayed in the cell.
$DAY Inside special tags that loop through days, the $DAY variable is set to the current day in the loop. Properties of $DAY are the same as those in each grid cell above. Special tags listed above also reference the current day held in the $DAY variable.


Retrieving Events

Each template is responsible for retrieving the events it wishes to display, if any. This is the job of the &getEvents() and &getEvent() subroutines.

The &getEvents() subroutine takes arguments which define which range of events to retrieve, then gets the events and schedules from the database and populates most of the variables and special tags listed above. The arguments are given in the form on a hash table of values. For example,
&getEvents( {range=>'month'} );
This will retrieve all events and their schedules for the current-displayed month.

The list of possible arguments to the function are as follows: The logic to determine the actual begin date and end date of the range to show is: So, to retrieve the current month's events, all you would even need to use is:
&getEvents({});
Since the range defaults to 'month' and the start date defaults to the currently displayed date.

The &getEvent() subroutine retrieves the details and schedule of a single event, and is passed the event ID.


Customizing Admin Templates

The entire Calendar Admin interface is template-driven also. However, the templates used in the Calendar Admin do not have special tags, and any special variables are not documented. The Admin templates are often somewhat complex and filled with Perl code, and should only be changed if you are very familiar with HTML and Perl.

Changing the Calendar Admin templates will allow you to dramatically change the look and feel of the Admin application, as well as customize its behavior and features. This is a task for advanced users only!

Language Translation

Language translation of the calendar display interface is taken care of by changing day names and month names in the Calendar Settings page of each calendar, as well as changing the text used in the display templates.

Translating the Calendar Admin application is a little more complex, although well supported and fairly straight-forward.

Under the calendarscript/templates/admin/ directory exists a different directory for every language currently supported by the Calendar Admin application. Currently, the only language supported is Enlish. However, you can easily translate to another language by copying this directory and renaming it to the language of your choice. Then go into all the template files of this new directory and translate the text in them. The final step is to translate the file called 'messages.txt' in the same directory. These are the messages that the Calendar Admin script itself generates in the case of warnings, errors, and other usre messages.

Once the translations are complete, log into the Calendar Admin application and navigate to the 'Admin Interface' screen. Here you will find the name of your new directory under the Language setting. Select your new language translation, save the changes, and your Calendar Admin interface will now be in your new language.


Plugins
Concept

Plugins allow a developer to extend or customize the functionality of CalendarScript without modifying the distributed code or files. Entirely new functions can be added to the script and distributed to others, enabling CalendarScript to become very modular and flexible.

A Plugin is simply a directory containing files that conform to the Plugin specifications (below). Once a Plugin is installed and enabled, the application will look for Perl subroutines, template files, etc within files in this directory. Everything needed for a Plugin to operate is contained in one single directory.

An example Plugin is included in the distribution which gives you an idea of what can be done and how simple it is. This Plugin doesn't do anything useful, but is provided as a reference to get a Plugin developer started.

What Plugins Can Do

A Plugin can do any of the following, in any combination:
The Basics

As mentioned before, a plugin is just a directory which contains files. This allows a Plugin to be distributed as a zip file which can simply be unzipped in calendarscript/plugins/ and instantly be available through the admin interface. There are no code changes or configuration file changes necessary - once the files are unzipped into the correct directory, the plugin will be available to be activated.

Each plugin has its own directory, and these directory names must be unique. Inside this directory one file is required - readme.txt. This file contains information about the plugin which will be shown in the Manage Plugins screen in the admin interface. The example plugin shows the format of the file:
# Example Plugin
name:Test Plugin
description:This is a test plugin...
author:Matt Kruse
author_email:matt@calendarscript.com
url:http://www.CalendarScript.com/
Lines beginning with # are comments and are ignored. The other lines are simply a field title and its value, separated by a colon (:). The only required field is 'name'. The others will be displayed in the Manage Plugins screen to provide more information to the user, if they are supplied.

Adding Permissions

A plugin may wish to add functionality that is only available to users with certain permissions. For example, you may wish to add a screen to the admin application, and restrict the screen to only certain users. To do this, the plugin needs to add a new permission to the User Permissions screen in the admin application, so that users may be granted this permission.

This is accomplished by adding a file to your plugin directory named permissions_list.txt. It can contain one or more specific permissions to be added to the application. The format of the file is tab-separated values like this example:
#type	name	description
GLOBAL	SOME_ACTION	Perform some action specific to a template
The first field is either 'GLOBAL' or 'LOCAL' which determines which section of the permissions screen the permission shows up as.
The second field is a unique identifier for the specific permission. This field can then be used in templates and actions to determine if the current user has this permission enabled or not.
The last field is the description of the permission. This is what will be displayed in the permissions screen.

Adding Admin Menu Options

If a plugin adds a new screen to the admin application, you will probably want to add an option to the Main Menu and the command drop-down list to navigate to your new screen. This is done by adding the file 'command_list.txt' to your plugin's directory. The format of the file is tab-separated values like this example:
#category   title   description   link   permissions_required
Calendar   Plugin Test   An Example   template=test.html   GLOBAL:SOME_ACTION
The first field is the category under which the new command option will appear. For example, 'Calendar' or 'Events' or 'Calendar Options'.
The second field is the title of the command option. This is the text that will become the link in the Main Menu, and what will appear in the drop-down menu.
The third field is the description of the command option. This is optional, and will appear after the title in the Main Menu only.
The fourth field is the link to be executed for the command option. Except for very rare conditions, this will be in the format 'template=file.html'. This means that the admin template 'file.html' will be loaded when the command option is selected.
The final field defines which permissions the user must have in order for this command option to appear in their menu. If left blank, all users will see the added command option. Otherwise, you can specify a comma-separated list of permissions in the format [GLOBAL|LOCAL]:PERMISSION. If the user has any of the permissions listed, the option will be available to them. A common scenario will be to add a new permission using the permissions_list.txt file, and then add a command option which requires that permission in order to be executed.

Adding And Overriding Templates

If your plugin adds a new template file for display in the admin application, simply include the HTML file in the plugin directory. It will automatically be found when the screen is requested. You can add any number of templates required by your plugin.

You may also over-ride existing templates in the admin application. Simply create a template file with the same name as a template file in the calendarscript/templates/Admin/English directory. The file will be detected, and your template will be used instead of the default template file. This way you can add custom functionality to the application without actually changing the default distribution files. For example, you may wish to create a plugin which changes the Schedule Event screen to allow for a different interface, or limit the scheduling possibilities for users.

Adding Custom Functionality

The true power of plugins comes from their ability to change the underlying functionality of the CalendarScript application, and to add new functionality. This is done by writing Perl code and placing it in files with specific filenames, containing subroutines with specific names.

Inside the CalendarScript application are embedded a variety of "hooks". That is, places in the application where external functionality can be plugged in and executed. A plugin can define functionality for any of these "hooks" which will be executed when they are encountered.

The main admin application code consists mostly of code to execute for various commands which are sent from the templates. For example, 'login' or 'add_event' or 'delete_user'. Your plugin can supplement the default functionality by doing one of the following:
  1. Execute some code before the default command-processing code, and then let the default code continue to execute.
  2. Execute some code before the default command-processing code, and choose not to execute the default code.
  3. Execute some code after the default command-processing code has completed.
This type of functionality is probably best explained through an example, and for this example the 'add_event' command will be used. If you examine the code in calendar_admin.pl, you'll see the 'add_event' section, and also where the &handleCustomFunction() "hooks" are located. The following are examples of how the above three types of hooks would be implemented: To find out exactly which hooks are available and when they are executed, examine the source code in the application.

Finally, you can define a custom command in your template, and define the subroutine required to process that command. This way, you can add totally new functionality rather than hooking into an existing command-processing routine.
An example would be a plugin which adds entirely new functionality to the application, defines a template to get user input, and then defines a custom command to do something with that input.
If your command name is 'add_stuff' for example, then the hook name becomes 'command_add_stuff'. Therefore, the plugin would need to have a file named 'command_add_stuff.pl' and define the subroutine &command_add_stuff().



Advanced Usage
SSIs

A common use of a calendar system is not only to display a calendar of events display page, but also to list upcoming events on another page, such as the home page of a site. This is done using Server-Side-Includes, or SSI's for short. This will assume that you are familiar with SSI's, their syntax, and how to enable them on your web server.

A typical use of SSI's would be to list today's events on the main page in a list form, providing just a few details and then linking to the main calendar for more details. To accomplish this, a new template file should be created that is used only to display when the calendar is being called through SSI's. This template should be simplified and contain just the HTML output that will be inserted into the HTML of the containing page.

Arguments cannot be passed to CGI scripts running in an SSI environment on most servers. Therefore, another method must be used to pass preferences (such as which template file to use for formatting the output) to the script. Therefore, if the script is run and detects that it is running via an SSI call, it will look for a file called 'ssi.txt' in the 'calendarscript' directory. This file should contain any arguments that the script should process, such as defining which calendar to use, which template, etc. An example of this can be as simple as:
template=ssi.html
This would use the default calendar and the template file called 'ssi.html' in whichever template directory is currently configured for the default calendar. It would up to the template to retrieve only today's events, for example, using a call to &getevents() like:
&getEvents( { duration=>'1d' } );
When using SSI's, there is no way to use multiple calendars. Since arguments cannot be passed to the CGI program, there is no way for the script to determine which calendar it should be using, so it must run off one single config file, no matter how many calendars are actually setup in the application.


Command-line

The calendar script may be used as a command-line tool to generate HTML output. This may be useful in cases where you will run the calendar script locally on your own machine, using your own personal web server, and generate HTML pages showing the calendar of events which you will load on to your web site by hand. This is not the preferred approach, of course, but it is possible.

To run the script on the command-line, you must define the $BASE_DIR setting manually. See the Troubleshooting Installation section for details on how to do this.

The calendar should then run correctly from the command-line, and output an HTML page. The default calendar will be shown, using the default template, for today's date. In order to change the calendar used, template used, etc, you need to pass arguments on the command-line. These arguments are in the name=value format. For example:
calendar.pl calendar=test template=static.html month=1 year=2005 date=1 range=week
This will generate output for the 'test' calendar, using the template file 'static.html' and display the events for the week of 1/1/2005.


Security Considerations
Changing File Locations

By default, your 'calendarscript' directory will exist in the same place as the actual CGI perl script files, usually in the cgi-bin folder. There are two cases where this will not work well, however:
  1. If no files or directories under the cgi-bin directory can be set with CHMOD 777.
  2. If your web server is mis-configured, and a web browser can browse through the contents of the 'calendarscript' directory.
Most web servers will not allow people to browse the contents of anything under the cgi-bin directory. If a server is not configured properly, however, a user might be able to load the /cgi-bin/calendarscript/ directory in the browser and look at the contents. This would include the config files, events files, and schedules for all events. If you have calendars which are password-protected or events which are private, or if you are just security-conscious, this is not acceptable.

In these situations, it is recommended that you move the 'calendarscript' directory to another file location, preferrably outside of the document root of the web server.

Doing this will cause the script to longer be able to find the files anymore, however, so you must then go in and edit the $BASE_DIR line in the two Perl scripts to point to the new location of the files. For instructions on how to do this, see the Troubleshooting Installation section.


Encrypted passwords

Passwords for users are stored in the users.txt file, in encrypted form. This means that even if someone is able to view the file, they will still not be able to view the actual passwords.

Some systems, however, do not support Perl's crypt() command which encrypts the password. If this is the case, then the program will either fail or the passwords themselves will not be encrypted.


File locking

Since the calendar is a multi-user environment, meaning different people may be editing configuration entries or adding events the same time, file locking is required. This prevents two processes of the script from colliding with each other when reading/writing data to/from files at the same time.

Some systems, however, to not correctly implement Perl's flock() call to lock files. If this is the case, then the application will continue to function as normal, but files will not be locked and corruption of data is possible. For this reason, do not use operating systems such as Windows 95 to serve this program.