Plans, the best web calendar.
Users say:
Awesome program - I Love it.


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:

The .cgi file
owner group public
rwx r-x r-x
The .xml files
owner group public
rw- rw- rw-
All other files
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!

Great! Start adding events. (don't forget to change the default calendar password from "12345").

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:

###css file### Replaced with the URL of the calendar's css file.
###version### Replaced with current version of Plans.
###current calendar title### Replaced with the title of the calendar the user is viewing.
###include filename### Replaced with the contents of filename

This only works when the template itself is loaded from the local filesystem. Custom calendar-specific templates in Plans are loaded with a http request. It would be a major security flaw if these could load arbitrary local files.
###javascript stuff### Plans inserts lots of javascript at this location.
###debug stuff### If plans needs to report any errors, they'll show up here. Otherwise, this special tag will be deleted.
###tab menu stuff### This is where the tabs (Calendars, Add/Edit Events, Calendar Settings) go
###calendar controls### Controls which let the user select the month, year, etc.
###calendar area### The calendar itself is displayed here.
###export calendar link### Replaced with a link to export the current calendar data in various formats.
###add event to current calendar link###
###edit calendar options link###
If you're not using the tabs, these tags are equivalent to the "add/edit events" link and the "calendar settings" link.

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.