CalendarScript Documentation

Web Hosting by Netfirms | Free Domain Names by Netfirms

Calendar Script Instructions (from www.calendarscript.com/documentation/3.html)

Calendar Script instructions

Download

Download the .zip file from the download section.

Uncompress the archive

To uncompress the zip file, use a utility such as Winzip on your local computer and extract the files to an empty directory on your drive. You can obtain an evaluation copy of WinZip at www.winzip.com. WinZip should automatically create subfolders containing many files which are needed by the calendar application.

Modify Perl Scripts

1) Netfirms requires perl CGI scripts to have the extension .cgi so you need to rename the calendar.cgi & calendar_admin.cgi to a cgi extension.

2) You do not need to change the shebang line on this script as netfirms uses the same path as the default for the script.. By default, this line reads #!/usr/bin/perl which is the path to perl on the netfirms server.

Transfer files to the web server

All the files and directories now on your local computer need to be transferred to your web server via FTP.

To FTP the files to your server, connect using WSFTP. Navigate to the cgi-bin folder whick is where your CGI perl scripts need to go, and transfer the whole directory structure in ASCII mode (all files that were unzipped, upload exactly as they are uploading entire folders & their contents as is). 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.cgi and calendar_admin.cgi in the CGI directory, and a subdirectory called 'calendarscript' beneath that directory, containing all the rest of the files. WSFTP will allow you to transfer entire folders at once.

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.

Change the file permissions using FTP to allow the scripts to be executable and the data files to be writable.
File permissions must be set as follows:

calendar.cgi = CHMOD 755
calendar_admin.cgi = 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.

Run the Admin application

At this point, the aplication should be ready to run. To start the setup process, load the calendar.cgi file in your web browser. The URL is below:

http://yourmembername.netfirms.com/cgi-bin/calendar.cgi

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.cgi application is working. Load it in your web browser. The URL is:

http://yourmembername.netfirms.com/cgi-bin/calendar_admin.cgi

If the 'Setup Wizard' screen loads successfully, you are all set!

If there are any errors shown or if it doesn't work, go through the above process again, making sure you uploaded all the files & folders exactly as they were unzipped, uploaded in ascii format, & set the proper permissions.

If you are still unsuccessful, 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.cgi'. This will be in the same directory as your 'calendar.cgi' file. Try to run it via the web browser just like you would run calendar.cgi. If there is anything wrong with your installation, such as missing files, incorrect permissions, files not in ASCII format, etc, it will detect the problem and inform you.
If the debug.cgi script does not run correctly, see the next solution.

PROBLEM: 500 Internal User Error, or other generic webserver error message

SOLUTION:
2. Make sure all files were transferred to the web server in ASCII (Text) mode.
3. Verify that the calendar.cgi and calendar_admin.cgi 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.cgi and calendar_admin.cgi 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 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.cgi and calendar_admin.cgi. 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.cgi 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.cgi for your main page.

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

Grid/List : Grid view (default) displays the common calendar grid format, or an hourly grid in a daily view. List format is more condensed and only shows those days which actually have events scheduled.
Date Range : Common date ranges are just a click away. The 'Today' link will always bring you back to today's date, in single day view.

2. Calendar Functions

Search : Provides a search screen to find events. The search criteria fields are determined by settings made in the Admin application.
Login : Login to the calendar display to enable more event editing functions in the left panel, depending on security permissions of the user you are logging in as. After logging in, you will see your username above the calendar display.
Add Event (If logged in and security permissions allow) : Link directly to the 'Add Event' screen of the Admin application for the displayed calendar.
Edit Events (If logged in and security permissions allow) : Displays the 'Edit Events' screen of the Admin application for the displayed calendar and current month, so you can quickly and easily edit/delete events.
Admin : Takes you to the main page of the Admin application for the displayed calendar, so you can perform other tasks.
Logout : Log out of the display.

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.cgi 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.cgi?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.cgi 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.'

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.

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.

Weekly : Select one or more days of the week
Monthly :
- Select any individual date of the month. If a date selected is higher than the total days in any given month, the event will not occur on those months.
- Select a relative day of the month by selecting either First, Second, Third, Fourth, or Last and then either 'Day' or a specific day of the week.
Yearly :
- Select a specific month and date that this event occurs on every year
- Select a relative schedule in the same way as the Monthly option, but also select which month it applies to every year.

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.

Display Name: The text that will be displayed next to the value or form input for the field.
Unique Field ID: This is the column name that the field is stored under in the database. It is automatically populated with a suggested value based on the value entered for Display Name. This value is only used internally and never displayed. Each field must have a unique value.
Description: The full description of the field.
Required: Whether or not a value is required for this field in the Add form.
Display in Add Form: Whether or not to display this field in the Add form.
Display in details: Whether or not the value of this field should be displayed in the Event Details.
Searchable: Whether or not the field will appear in the criteria in the Search screen.
Form Input Properties: These options control how the field will appear in the Add form, and what type of input field it will be. Not all options apply to all types of inputs.
- Input Type: The type of HTML form input to represent the field.
- Default Value: For text or textarea types, the value that should be filled into the input by default.
- Size: For text or password types, the size of the input box.
- Maxlength: For text or password types, the maximum number of characters allowed in the input box.
- Rows: For textarea types, the number of rows of the input area.
- Cols: For textarea types, the number of columns of the input area.
- Value if checked: For checkbox types, the value to store in the database (and the value which will be displayed in the details) if the checkbox is checked.
- Checked as default: For checkbox types, whether or not the checkbox should be checked by default.
Select Box: For selectbox types, this set of controls defines the options that will appear in the option list. Each option has two values - the display text and the value of option. The display text is what will actually appear in the drop-down list as a choice. The option value is what will be stored in the database and will be displayed in the details for the event. These are often the same.
- Adding an option: Enter a value for the 'Display Text' and 'Option Value' and then click the 'Add' button. This will add it to the list of options under 'Current Options'.
- Removing an option: Select an option and click 'Remove'. It will be removed from the 'Current Options' list and its text and value will be put into the boxes on the left.
- Editing an option: To edit an option, remove it, modify the values, and add it again.
- Ordering options: The items will appear in the drop-down list in the order that they appear on the screen here. To move an option up or down, select it and click the 'Move Up' or 'Move Down' button to the right.
- Selecting a default value: By default, the first option in the list will be selected. If you would like a different option to be selected by default, select it and click 'Make Default'.

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:

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.
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.
The delimiter used to separate fields, both in the header row and the text
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:

Add User
Edit Delete Users
Modify Global Permissions: This allows the user to edit this group of permissions itself, which would allow them to grant the 'Add User' permission to other users, for example.
Customize User Database: Customize the fields that define the user databasse.
Manage Calendars: Add/Edit/Delete calendars from the system.
Feedback/Support: Access the Feedback and Support screen.

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:

View Calendar: This option only applies if you have the 'Require Login' option turned on in the Calendar Settings screen. If enabled, only users who have the 'View Calendar' permission will be able to login and view the calendar.
Add Event: Add an event into the system and schedule it, pending approval.
Edit/Delete Events: The ability to edit and delete any event in the calendar, no matter who entered it.
Edit/Delete Own Events: The ability to edit and delete only the events that this user added himself.
Approve Pending Events: The ability to approve any pending events entered by people with the 'Add Event' permission.
Automatically approve own events: When adding an event, it will not be marked as pending, but will instead be immediately added to the calendar.
Customize Event Fields: Change the fields that define an event in the database for this calendar.
Calendar Permissions: Modify these permissions for other users. When this option is enabled but 'Modify Global Permissions' is not, then this user will not be able to assign permissions for third column. These options will not be available.
Calendar Settings: Modify the settings and configuration of the calendar.

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.

Display Template Type: If there are multiple template styles defined in the templates directory of the application, this select box allows you select which templates style will be used to display this calendar.
Require Login: If you want your calendar to be password-protected, enable this option. Then before anyone can load the calendar display, they will be forced to login and must have 'View Calendar' permissions on the calendar they are trying to view.
Weekday Names: Change the names and abbreviations used for weekdays in the calendar, for language translation or any other reason that you wish to use different names. Day name 1 should always be used for the translation of 'Sunday' regardless of which Week Start Day you select.
Week Start Day: Many countries display their calendar grid beginning with a day other than Sunday. Change this option to begin the calendar on a different day. The number matches the day name above.
Month Names: Change the names and abbreviations used for months in the calendar.
Date Format: Choose the date format that will be used to format dates throughout the calendar. This allows you to change to the European format of MM/dd/yyyy, for example, rather than the default American format. You can also use the other format options if you wish to use a custom format.
Time Format: Choose between 12-hour and 24-hour formats.
Allow HTML: If you wish to put HTML into your event descriptions or other fields, this option must be enabled. However, if the HTML entered is incorrect or incomplete, it may cause the application to display incorrectly when the event is shown. For this reason, this option is turned off by default.
If HTML tags are used when this option is turned off, and then the option is turned on, it will not affect events entered previously. They will still not display the HTML. Likewise, if HTML tags are entered when this option is on, and then it is turned off, the HTML will still be displayed. This option only affects the event when it is actually added.
Auto-Link: When events are displayed, any text beginning with http:// can be assumed to be a URL, and the program can automatically hyperlink the text to the URL. This way links can be included in events without turning on the 'Allow HTML' option.
The TARGET attribute is added to links added by the Auto-Link option. The default value is "_blank" which causes all links to open up in a new popup window. If you would like links to open up in the same window and replace the calendar display, set this value to be empty.
Time Zone Offset: If your web server is physically located in a different timezone than your or your users, the calendar display may not be correct. For example, if it is Monday at 10:00pm for you on the west coast, but your web site is hosted by a company on the east coast, thenit will be 1:00am there, and the calendar will display the current day as being Tuesday. You can adjust for this by setting the timezone offset to add or substract a certain number of hours from the web server's clock. The text above the select box displays both the web server's time and your local computer's time so you can correctly configure the difference.

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.

Key: This is the unique ID of the calendar itself This will be the name of the directory that will hold the files, as well as the name used to load the calendar from the display. For example, if you give a key of "test" then you would load this calendar by loading /cgi-bin/calendar.cgi?calendar=test in your browser.
Name: The display name of the calendar.
Description: The calendar's description.
Copy Calendar: You can make an exact copy of another calendar, including its events and configuration, by selecting one from the list. Permissions are not copied. Leave this blank to create a calendar with the default options and no events.
Give Full Permissions To: When creating a new calendar, there is often one user of the system who will be the administrator of this calendar. You can select a user from the select list who should be setup with full permissions on this specific calendar when it is created.

Admin Interface

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

Admin Template Language: If multiple language directories exist for the Admin templates, you can select which language to use.
Default Calendar To Display: When the calendar display is loaded without specifying which calendar to display, this defines which calendar is loaded.
Color options: These options change the display colors for screens in the Admin Interface. Either type in a valid HTML hex code, or you can use the color picker popup window. Click the 'Pick...' link and a popup window will give a grid of the web-safe color palette. Click a color to select it.
If you have a current browser version, color selections will be instantly visible when you change a value. This way you can change values into you find a color combination that you like, and then save it.
Saving color changes takes effect immediately, and when the screen re-draws the new colors will be used.

Feedback/Support

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

Security Considerations

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.