Finally, I would like to also keep a list of implementations of this script. If you are using the script, please drop me a message so I can at least take a look at it.

Finally, before doing anything else, read this file, and then read it again. This is the primary source of information on this script, until I can get comments into the main files, and most of your questions will be answered here.

SETTING PERMISSIONS

If you are installing this script on a UNIX web server, you will need the following information to set the permissions properly on the files that compose this script. Each subdirectory and file has its own correct permission level associated with it. Please read this and the next section carefully, as incorrect permissions is the number one reason why the script won't work after installation. The following table is a quick guide to setting permissions on a UNIX server. The actual settings for the files and directories follow in the next section. PERMISSION COMMAND rwxrwxrwx chmod 777 filename rwxrwxr-x chmod 775 filename rwxr-xr-x chmod 755 filename rw-rw-rw- chmod 666 filename rw-rw-r-- chmod 664 filename rw-r--r-- chmod 644 filename TOP | BASIC INSTALLATION

DIRECTORIES AND FILES

If you extract the files from the archive using the directories supplied, you will get a directory structure that looks like the following, a collection of subdirectories and files. The permissions for each file and subdirectory are listed next to each. calendar root directory (drwxr-xr-x) usually cgi-bin |____dbs (drwxrwxrwx) sub-directory | |____demo (drwxrwxrwx) sub-directory | |____calsf (drwxrwxrwx) sub-directory | |____events (drwxrwxrwx) sub-directory | |____auth.setup (-rw-r--r--) | |____calendar.altusers (-rw-rw-rw-) | |____calendar.counter (-rw-rw-rw-) | |____calendar.setup (-rw-r--r--) | |____calendar.users (-rw-rw-rw-) | |____help.setup (-rw-r--r--) |____framecal (drwxrwxrwx) sub-directory | |____fc_admin.pl (-rwxr-xr-x) | |____framecal.pl (-rwxr-xr-x) |____help (drwxr-xr-x) sub-directory | |____1.txt (-rw-r--r--) | |____2.txt (-rw-r--r--) | |____3.txt (-rw-r--r--) | |____4.txt (-rw-r--r--) | |____5.txt (-rw-r--r--) | |____6.txt (-rw-r--r--) | |____7.txt (-rw-r--r--) | |____8.txt (-rw-r--r--) | |____9.txt (-rw-r--r--) | |____10.txt (-rw-r--r--) | |____11.txt (-rw-r--r--) | |____12.txt (-rw-r--r--) | |____90.txt (-rw-r--r--) | |____91.txt (-rw-r--r--) | |____92.txt (-rw-r--r--) |____libs (drwxr-xr-x) sub-directory | |____auth-extra-html.pl (-rw-r--r--) | |____auth-extra-lib.pl (-rw-r--r--) | |____auth-lib.pl (-rw-r--r--) | |____auth-server-lib.pl (-rw-r--r--) | |____cgi-lib.pl (-rw-r--r--) | |____cookie-lib.pl (-rw-r--r--) | |____mail-lib-unix.pl (-rw-r--r--) | |____mail-lib-win.pl (-rw-r--r--) |____utilities (drwxr-xr-x) sub-directory | |____convert_db.pl (-rwxr-xr-x) | |____strip.pl (-rwxr-xr-x) |____user_help.pl (-rwxr-xr-x) calendar is the root directory for the application and must have its permissions set to be readable and executable by the web server. The default is usually your cgi-bin directory. dbs is a subdirectory that contains the subdirectories for each individual calendar that you run from your server. demo is a subdirectory that contains the files for the demonstration calendar distributed with the application. When you set up a new calendar, you should create a new directory for it underneath the dbs subdirectory. The following files are stored in this subdirectory for each calendar: auth.setup is the file which contains all of the authorization variables for the script. These variables allow you to tweak the access characteristics of the calendar. See the documentation below for information on all of the variables stored in this file. calendar.altusers is a file which must be enabled in the auth.setup file. Basically, it allows you to filter who gains access to the calendar. If you set you calendar up as such (see below), users, when registering, will be added to this file. You can then move them over to the calendar.users file (see below) at your discretion, which will then, and only then, allow them access to view the calendar. calendar.counter is a file which is used to keep track of the number of events posted to the calendar. Each event must have a unique ID number, and that number is provided by this file. When starting a new calendar, this file should contain only the number "1". calendar.setup holds all of the variables to customize one installation of the calendar. If you use more than one calendar, you will need a calendar.setup for each in its own directory. This file will be explained in greater detail later. calendar.users will contain the list of all the registered users and their personal info. It will be filled automatically by the script as people register on your calendar. Note that a default admin account is stored in this file when distributed. The username is admin, password is admin. When you first set up your calendar, register for an account, then sign in with the default admin account, and register yourself if need be. Then, set your new account to admin access via the "User Admin" button. Now, sign in with your new account and delete the default account. You don't want someone coming behind you with the default and messing with your user database. help.setup holds the variables to customize the online help script. This file will be explained in greater detail later. calsf is a subdirectory that must be added to each calendar application directory. This directory stores all of the session files that are generated to track users through the calendar, saving the users security information. The files will be automatically written and pruned by the script. events is a subdirectory that must be added to each calendar application directory. This directory will store all of the files that define an event. The file names will simply be numbers corresponding to the id numbers for each event. Now you know one of the reasons why each event must have a unique id! help is a subdirectory containing the text files for each help topic covered within this script. The files are read in by topic number as needed by calendar.pl and the authentication libraries. Do not change the name of these files unless you find them in the appropriate script and change them there as well. The contents of the files can be modified if you like, as they contain only html. libs is a subdirectory containing many files that are commonly used for authorization purposes and supporting libraries. They are commonly used by a number of Perl CGI scripts, not just FrameCal, so they should be stored in a common, separate directory for organization purposes. The following files are used, and thus distributed with this script: authentication libraries all start with "auth", and are used to authenticate users if password protection is implemented. cgi-lib.pl is used to read and parse incoming form data and to provide error messages in case the script cannot open a needed file. cookie-lib.pl is from Matt's Script Archive, and will be used if you choose to set up your calendar to allow users to save their login names and passwords. mail-lib-unix.pl and mail-lib-win.pl is used to mail the administrator and users dependent upon the settings in the setup file. All mail is optional. The file will require some customization for you particular setup. Read through the files. You will need to include in the file the location of the mail application, whether Blat or sendmail. Also, in the case of Blat, you will need to define a directory to write the temporary files Blat uses to send out email messages. Pick the file that indicates the OS your calendar will run on, and rename it to mail-lib.pl before uploading. framecal is the subdirectory that holds the executable files listed below. Note that you can install all of these in your cgi-bin directory, just be sure to modify all of your paths in the framecal.pl file. framecal.pl is the meat of the application, so to say, and must be set to readable and executable by the web server. Don't modify this file (much) unless you really know what you are doing. You will need to set a couple of variables in the beginning of the script, so open it up. If you don-t know Perl, but would like to try your hand at modifying this script, head over to the bookstore for some suggested titles. You will need to set the path to your libs directory, and you also may need to change the script to use absolute paths rather than relative paths for the calendar_type variable. fc_admin.pl holds all of the subroutines for admin use. These include listing out all of the registered and pending users, as well as routines to delete, register, and modify access level of the users. utilities holds a couple of scripts to make your life a little easier. convert_db.pl is a file that will allow you to upgrade your database file (calendar.events) from version 1.0+ to the new formats used by this version. Please note that you will need to place this script in the directory with your existing calendar.events file, and run it through your browser. You will have to have your events directory created prior to running the script. When done with the conversion process, remove this file. The script will not delete your calendar.events file, just in case there are any problems. strip.pl is a file that strips comments and blank lines out of a perl script. The framecal.pl file, for instance, is 94 Kb with the comments in, 50 Kb with the comments and blank lines stripped out. So, to make the script execute a little faster, run this script. You must run it from the command line. Provide it with a directory or directories as arguments, leaving trailing slashes off, and it will find all the files in that directory with the .pl extension, and remove all of the comments and blank lines out of them automatically, leaving much smaller files. I use this on my files before I upload them. Note that the original file will remain in the directory, renamed to the original file name with ".commented" added to the file name. user_help.pl is a supporting application that is built into the script. It supplies online help to the users of the calendar, if configured as such in the setup file. Each calendar will have its own setup file for the help application. The script works by taking the help topics defined in the script and reading the associated files from the help directory text files. TOP | BASIC INSTALLATION

AUTH.SETUP

The auth.setup file contains all of the variables that allow you to customize the accessibility characteristics of your calendar. Please read through these variables carefully and decide on how you will implement security for you calendar. $auth_lib : this is the variable that points to the location of the authorization files. If you put the authorization files in a separate directory, set this variable to the proper value. Normally, this variable is set to the same value as the $libs variable in framecal.pl and fc_admin.pl. $auth_server : this variable is set to "1" if you are using server based security, "0" if using CGI based security. If you don't know what server based security is, you are most likely dealing with CGI based security. Server based security would deal with ENV{'REMOTE_USER'} and you would be using the servers config files. CGI based security creates its own authentication routines. $auth_cgi : set this to "1" if using CGI based security, "0" if using server based security (see above). Note that if both of these are set to "0", you are using no security, in effect making it a free for all calendar, which may be exactly what you want. $auth_add_register : if this is set to "1", users entries will be added directly to the appropriate user database. If it is set to "0", they won't be. $auth_email_register : if this is set to "1", the administrator will be emailed whenver someone registers on the calendar. If it is set to "0", there will be no notification. $allow_public_access : if this is set to "1", a "Public Access" button will be displayed on the login screen. If this button is pressed, people will be able to view the calendar in read only mode without having to login to the calendar. This is helpful to keep your user database small if only a few people are posting. You can just remove anyone set to public access, if you don't mind other people looking at your calendar. Set it to "0" to disable. $auth_session_length : this is the number of days you want session files to be kept before they are deleted. $auth_allow_register : set this to "1" if you want to allow people to register on the calendar in any way, or to "0" to disable all registrations. $auth_allow_search : set this to "1" if you want users to be able to search the user database for an old account name. Set to "0" to disable. $auth_generate_password : set this to "1" if you want the script to generate a password and mail it to the user. Set it to "0" to allow the user to chose their own. $auth_check_duplicates : set this to "1" if you want the authorization script to check to see if the chosen username is already present in the database. If you are running this with access levels, setting this to on is a very good idea. If you don't want to listen to this advice, set it to "0". $notify_register : set this to "1" if you want an email message sent to a user automatically when their access level is changed by the administrator, or when they are upgraded from pending to active. Set it to "0" for no email notifications. $use_cookies : set this to "1" if you want to enable cookies for login purposes. By enabling this, users will be given the option to save their login information as a cookie, and be automatically logged on when they return to the script. Set it to "0" if you want to disable it. $auth_use_help : set this to "1" if you want to enable online help for the authorization scripts. To disable it, set it to "0". $auth_user_file : this is the file which contains the list of users who are authorized to use the script. Unless you have made some major modifications to your directory structure, leave it as is. $auth_alt_user_file : this is a file you can use to store users before you add them to the user database if you are not allowing users to add themselves instantaneously. This variable is included twice, one commented out. How this works is the following. If you use the variable with the calendar.altusers file specified, users will be added to this file when they register. They will not be able to access the calendar, unless you are allowing public access. If you set this variable, the administrator will have a button to view the pending users. You can select people from this file to upgrade to full users status, in effect moving them over to the $auth_user_file, and thus allowing them to access the calendar by logging in. This is a good option if you want to keep the calendar online and easily accessible, but want to really restrict access to it. $auth_default_group : set this to the access level you want new users set to when they register. This value will have no effect until the user is listed in the $auth_user_file. Set this to "public" if you want people to only be able to view the calendar until authorized to add events, "user" if you want them to be able to post events the first time they use the script, and "admin" if you want your calendar thrashed on a regular basis. ; ) $auth_admin_from_address : this is the address that will be used in the FROM field for any email generated by the script. This is a must. $auth_admin_email_address : this is the email address of the admin who is to receive registration notices. If "$auth_email_register" is set to on, you must have a valid email address entered here. $auth_session_dir : this is the location of the directory which will temporarily hold the session files for this calendar. Note that each calendar should have its own session file directory. $auth_register_message : this is the message that you want to appear when users are registered. You should change this is using the $auth_alt_user_file to something like "Thanks. You will be notified when your registration is accepted.". $auth_password_message : if using generated passwords, this is the message that will precede the password in the email message that is sent. @auth_extra_fields : these are fields, besides the default of password, username, and access level, that are stored in the user database. @auth_extra_desc : these are the names for the above fields. @auth_names : these are all of the names for the fields that will be used when generating tables of users. $auth_reg_name : this is the string that will be placed in the subject line when emails are sent notifying the administrator of new users. It will also be used when notifying users of registration status. $cookie_end_date : the end date of any cookies set by this script. Don't change this unless you know what you are doing. $auth_help_script : this is the location and name of the user_help.pl script, if using online help. $auth_help_setup : this is the location of the setup file for the user_help.pl script. auth.setup TOP | SETUP FILES

CALENDAR.SETUP

The calendar.setup file is a bit intimidating the first time you look at it. I have broken the variables into groups that are somewhat related to each other, and will cover each in turn. « File Locations | Year Information | Customization Variables | Arrays and Hashes » File Locations and Information These variables provide the calendar.pl script with information regarding the location of files and/or directories that will be accessed by the script. $this_script_url : this is the location of the main script. If you didn't change the file name, you don't need to do anything with this variable. $admin_script : this is the name and location of the fc_admin.pl script. If you didn't change the file name, you don't need to do anything with this variable. $path_to_events : this is the path to the events directory, relative to the framecal.pl file. $temp_lock_dir : this is the path to the calsf directory, relative to the framecal.pl file. $count_lock : this is the path an name to the counter lock file. $counter_file : this is the location of the calendar.counter file that is used to provide the script with a unique ID number for each event added to the database. Again, we use the $calendar_type variable so we stay in the correct calendar directory. $help_script : this contains the path to the user_help.pl script for use in generating the html tags for the links to the help files in the calendar script. $help_setup : just like $calendar_type holds the subdirectory to the setup files for the calendar, this holds the directory to the help.setup file for the calendar in question. $in_maintenance : if this is set to "1", whenever someone hits the calendar, they will get a message that the calendar is currently undergoing maintenance, and to please check back later. If set to "0", it does nothing. Setting this to one will allow you to do directory maintenance, file maintenance, etc., without giving bogus information to users and/or loosing information. calendar.setup Year Information These variables just provide the year limits for use in the script. $greatest_year : this is the greatest year that you want people to be able to access via the script. calendar.setup Customization Variables These variables allow you to customize the look of your calendar, so that it will blend in with the rest of your site. $bodytag : use this variable to set properties that would normally go in the BODY of your html document. Remember to use an absolute path to the background image, if any, and leave a leading space in the string, unless you are not using it at all. $hitxt : this variable sets the font color used in the column names row of the tables that are generated by the script. $basefont_tag : if you would like to specify a basefont for your calendar, set it here. You can specify font face, color, and/or size. $subjcol : this variable sets the color used for the subject line of an event when viewed. $apptcol : use this variable to set the background color for the cells of the column names in the tables generated by the script. This color should contrast with $hitxt above. $timecol : this one is used to set the color for the start time, location, and end time of the event when viewed. $evntcol : set this variable to the hex color value that will be used to hilite the cells that contain events in the month view. $tdycol : set this variable to the hex color value that will be used to hilite the current day when the month is viewed. $cal_name : the name of your calendar, displayed in various locations throughout the script. $notify_event : set this to "1" if you want the administrator to be notified via email every time an event is posted, modified, or deleted. Set it to "0" to disable admin event notifications. $use_help : set this to "1" if you want to use the online help provided with the calendar. $day_frame : when creating your frameset, you will need to name each frame in the set. Set this variable to the same value as the name of the frame in which you want to display day information. $month_frame : the same applies here as above, except this variable is set to the name of the frame in which you want to display the month view. $day_cell_width : this value is used to set the width of the cell for each day number when viewing the month. Depending upon the font you used in the basefont tag, and how wide your month view frame is, you can adjust this number to get the calendar to display well (read symmetrical). $use_time_zones : if your calendar will be used by people in many time zones, you can turn this on so that start and end times will display the time zone as well, for better organization. If set to "1", it is on, and will display. Posters will be prompted to enter a time zone for their events. If set to "0", they will not be displayed and there will be no prompt. $strip_html : if you would like to prohibit HTML tags in your event postings, set this to "1". Else set it to "0". $allow_notify : set this to "1" if you would like to allow notification of registered users of event additions, modifications, and deletions. If turned on, when an event is posted, the poster will have the option of selecting users to notify of the event. These values will be saved with the event. If the event is modified or deleted, the same people will be notified of the changes. Set this to "0" if you don't wish to use this feature. $allow_links : set this to "1" if you would like events to have an optional link to further information posted. If you turn this on, users will have the option to enter a link title and URL that will be displayed with the event. The link will be formatted to open a new browser window when selected, to prevent frame hijacking. Set this to "0" if you don't wish to use this feature. $old_events : this value is tied in with the &first_pass=on portion of the query string (see below). If you are using this, set this value to the number of old months you would like to maintain as a buffer. If set to one, events older than the current month minus one will be automatically deleted by the script the first time it is loaded. This allows you to automatically clean up your databases and directories, instead of manually going in every so often to do maintenance. $html_url : the full URL to your frameset page, for use with emails. This URL will be included in the email message to allow people to more easily get back to the calendar when notified of a calendar event. $time_offset : this variable is used for the display of the last modified property of each event. Basically, if your server is in a different time zone than your office, you can set this variable to the offset value, so that it appears as those the server is in your time zone. calendar.setup Arrays and Hashes These are the arrays and hashes used by the script for use by various parts of the script. @day_names : an array containing the names of the days of the week. %month_hash : an associative array ("hash") which pairs month names (values) with their numbers (keys). %TIME : a hash which pairs time values with military time keys. I covered all the times in a day every half hour in the demo. Feel free to reduce the number for your application, just be sure to remove them in their proper pairings. @time_zone_values : the time zones you expect your script to cover. I added this upon request of a user, as the script was being implemented on a script to organize events online, across multiple time zones, and we needed to be able to set a base time for the event. If you are not using time zones for your purposes, you don't need this array. @hour_values : an array of hour increments to be used to set the duration of an event. Feel free to shorten this array for your particular use. @mins_values : an array of minute increments to be used to set the duration of an event. If you change this, be aware of something very important: The end time of an event is taken by splitting the start time, and then adding the duration minutes and hours appropriately to get the end time. Thus, if you want to add "15" and "45" to this array, you will need to change your values in %TIME to be incremented on a 15 minutes basis. @field_names : this is an array of the column titles that will be used when creating the modify or delete events table within the script. @field_values : an array of the variable names associated with an event. @req_fields : an array containing the items from @field_values that are required for every event. calendar.setup TOP | SETUP FILES

HELP.SETUP

The help.setup file has only a few lines in it, and they are there mostly for formatting purposes. The following variables are defined: $bodytag : this variable is used to format the body element of the displayed file. Remember to use absolute paths to any background file that you may wish to use. $hi_txt : this variable is used for hilited text. $basefont_tag : this variable is used, if desired, to specify the basefont used for the displayed html. If you don't care to use a basefont tag, just set the value of this variable to "". $help_name : this variable is used as the displayed title for all windows opened with the help file. $admin_email : this variable will hold your email address for use in the footer of the displayed help files, so users can get in touch with you, if they need to, from the displayed help file. $help_dir : is the location of the directory that holds the help text files, either relative to the user_help.pl file, or with an absolute path. In the body of the user_help.pl file, the path to the libs directory is hard coded. If you place your libs files in a different directory, be sure to update the file. TOP | SETUP FILES

When you do add new calendars, be sure to create new calendar.counter, calendar.altusers, calendar.setup, calendar.users, and help.setup files to fill the new directory, and be sure to create subdirectories called "calsf" and "events" under it to store the session and events files.