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
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=vacationsThis 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.