I looked high and low for a good family calendar -- Plans is just right!!! Thanks so much!
Manual
Installation:
1. Get the files
After downloading plans, unzip the archive:
- (in unix, type "tar -xvf plans.tar.gz")
- (in windows, use winzip or similar utility)
And move the files to your webserver. If you're running on unix, you may want to move the entire archive to your server and unzip it there.
Unzipping the archive will create a directory named "plans" with all the plans files beneath. You may want to rename "plans" to "calendar" or something similar.
2. Set permissions
You will need to adjust the permissions of plans.cgi, so the server recognizes it as an executable file. The .xml files may also need permissions set so the script can modify them.
The process for doing this can be different for each server, but in general, the permissions should be set as follows:
| owner | group | public |
| rwx | r-x | r-x |
| owner | group | public |
| rw- | rw- | rw- |
| owner | group | public |
| rw- | r-- | r-- |
(rwx = read, write, execute)
Note--A common source of errors is setting all the files to read, write, and execute. Some servers won't run scripts that have these permissions.
Most ISPs have directions for how to set up perl cgi scripts in their environment.
Plans expects perl to be located at /usr/bin/perl. If your server has a different path for perl, you'll need to change the first line of plans.cgi.
3. Test it out!
Point your browser at the URL for your plans.cgi file (something like http://www.mysite.com/calendar/plans.cgi) and see what happens.
Hooray, a calendar appears!
Oh no! I get the dreaded "500 internal server error"
- If you used ftp to upload the files, make sure you used the correct mode (binary mode for graphics or zip files, ASCII mode for everything else.)
- Double-check those permissions...
- Does your ISP have any special rules or instructions for running perl scripts?
- If all else fails, ask for assistance on the forum
My browser displays the source code to the script.
This means your server is treating the script as a data file, instead of something to be executed. Double-check the permissions again. If they appear to be set correctly (the script has executable permissions), contact your host's support and tell them your perl cgi script won't execute.
Some hosts have strange rules for executing scripts. They may require scripts to be in a special directory (often called cgi-bin). They may require perl scripts to end with .pl.
A calendar appears, but one of the tabs is missing. What's up?!
This probably means one of your .xml files doesn't have write permissions. If the events.xml file isn't writable, Plans won't display the "Add/Edit Events" tab. If the calendars.xml file isn't writable, Plans won't display the "Calendar Settings" tab.
A calendar appears, but there are no borders, fonts or colors...
This means your host doesn't allow static files (css files, template files, etc.) to be located under the directory where scripts are at.
Edit your plans_config.pl file, and find the text shown below. Do what it says (move the theme/ directory to another spot, so the plans.css and plans.template files can be located with a web browser.
######################################################################################################## ############################### File Locations ############################################# ######################################################################################################## # This is the default file structure for plans: # # plans/ # plans.cgi # plans.config # events.xml # calendars.xml # theme/ # plans.template # plans.css # icons/ # graphics/ # # If you move the theme directory to a different location for some reason # (for instance, if your server does't allow static files be served from # the same directory (or subdirectories) as scripts, uncomment the variable # below and set it accordingly. # $theme_url = "http://your.domain.com/calendar_theme"; # note there is no end slash!
Just a few lines farther down in plans_config.pl, you'll find the $default_template_path variable. This must also be changed if you move the theme/ directory.
As noted in the comments, $default_template_path is not an URL. It's a filesystem path. A common mistake by first-time Plans users is to assume it's an URL like $theme_url (and put "http://" in front of it).
########################################################################################################
############################### Default Template #################################################
########################################################################################################
# All calendars use the same default template file, specified below.
#
# Calendars can have their own custom template files, which override the default file.
# this custom template file must be an URL (plans will fetch it across the network, even
# if it resides on the same server). This increases security and allows template files to
# come from other websites.
#
# If a calendar doesn't specify a custom template file, or plans is unable to fetch the custom
# template file, it will use the default template file below.
$default_template_path = "theme/plans.template"; # On windows, the you might have to change this to something:
# like: "C:/path/to/plans/theme/plans.template"
# IMPORTANT -- this is not an URL. It's a filesystem path.
Diagnostic Mode
For troubleshooting, Plans has a "diagnostic mode" that simply lists most of the settings from plans_config.pl.
To activate this mode, point your browser at:
http://your.domain.com/plans.cgi?diagnostic_mode=1
(replace http://your.domain.com/ with the real URL for your Plans installation).
Diagnostic mode only works after Plans is running. It's not much use in figuring out why Plans won't run. It is helpful, however, in troubleshooting problems with the theme/ directory.
SQL Database support
The default installation of Plans uses flat files (not a database). If you don't know anything about SQL, you can run the calendar just fine with the flat-file method. If you don't know about SQL and want to learn, this is as good a time as any :)
Plans supports mySQL databases using Perl's DBI database abstraction layer. In theory, this means Plans should be able to use any SQL database, but it has only been tested with mySQL.
To use mySQL, you'll need a working installation of Plans (Plans uses flat files by default). Then:
1. Create the database.
2. Edit plans_config.pl and set the $data_storage_mode variable to 1. Also set the database variables (database name, username, password, etc.) to the appropriate values.
3. Point your browser at plans.cgi. It will try to connect to your database. If successful, it will create the necessary tables for you. Plans will prompt you for whether to transfer calendar data from the flat files to the SQL tables.
Print support
Plans uses a separate set of css style attributes to control printing. You can vary these by changing plans.css below the @media print line.
When printed, Plans looks like this in Internet Explorer 6.0 and this in Mozilla Firefox. This is with background colors & images turned off, like so:
In internet explorer 6.0:
Tools → Internet Options → Advanced → Printing → "Print background colors & images"
In Mozilla Firefox:
File → Page Setup → "Print background (colors & images)"
Customizing the calendar
When you edit any of the config files, use a good text editor. Notepad is not recommended, SciTE is an excellent editor for windows.
The first file you should customize is plans.template. It's just a normal html file, with some ###special tags###.
Below is a list of the special tags you can use in plans.template:
The plans.template file actually contains two templates. Below the main calendar template is another chunk of html which is used for the event details pop-up window.
Below is a list of the special tags you can use in the event details template:
| ###event date### | Replaced with the event's actual date |
| ###event icon### | Replaced with the event's icon, if there is one. |
| ###event background color### | Replaced with the event's background color |
| ###unit number icon### | Replaced with the unit number icon (this feature is from the days when plans was a scout troop calendar. It is now turned off by default. The on/off switch is in plans_config.pl.) |
| ###event title### | Replaced with the event's Title |
| ###event id### | Replaced with the event's id (plans uses this unique id to track each event) |
| ###event calendar id### | Replaced with the id of the event's calendar (plans uses this unique id to track each calendar) |
| ###event calendar name### | Replaced with the name of the calendar this event is part of. If the calendar has a link, this text will be clickable. |
| ###edit_event_link### | Replaced with a link to edit the event. |
| ###delete event link### | Replaced with a link to delete the event. |
| ###export event link### | Replaced with a select box that allows the viewer to export the event. |