|
Installation
Installation1. Get the filesAfter downloading plans, unzip the archive:
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_x.x.x" (where x.x.x is the plans version number, e.g. 7.8.4) with all the plans files beneath. You may want to rename "plans" to "calendar" or something similar. 2. Set permissionsYou will need to adjust the permissions of plans.cgi, so the server recognizes it as an executable file. The .xml files in the data/ directory will 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:
(rwx = read, write, execute) If plans.cgi can't find "data/calendars.xml" and the other .xml files, you should check and make your sub-directories accessible. 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. Note--The first time Plans runs and after each upgrade, Plans automatically translates the language strings in its language file(s) into a javascript language file - plans_lang.js You may need to temporarily adjust rights to the plans_lang.js file to allow write access for the user the web server is executing under if this is something other than the file owner. It's safe to set back after this initial run. 3. Test it out!Point your browser at the URL for your plans.cgi file (something like http://www.yourdomain.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"). You can customize the look of your calendar by editing the file plans.template in the theme directory (instructions are [http://planscalendar.com/doc/doku.php?id=doc%3Astart#customizing|Here]). Oh no! I get the dreaded "500 internal server error"
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. Make sure you uncomment the line by removing the # from in front of the $theme_url line.) ######################################################################################################## ############################### File Locations ############################################# ######################################################################################################## # This is the default file structure for plans: # # plans/ # plans.cgi # plans.config # data/ # *.xml # theme/ # *.js # plans.template # plans.css # icons/ # graphics/ # # The theme/ directory contains static files (.css, .js, .gif) # If your server does't allow static files be served from the same # directory (or subdirectories) as scripts, # # You can move the theme directory to somewhere outside the plans directory. # If you do this, uncomment the variable below and set it accordingly. # You'll also need to change the default template file in the next section. # $theme_url = "http://www.yoursite.com/theme_directory"; # 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.
#
# 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, 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.
There's some weird CGI::Session error...Plans error: unable to locate required module CGI::Session! This means the server does not have a required perl library installed. Many hosts will be willing to install this module for you if you ask. If for some reason you are not able to install this module, you can still run Plans just fine - you'll just need to disable sessions in plans_config.pl. This forces users to enter the calendar password each time they add or change an event. Setting/Changing Passwords
Resetting a password if you forgot itThere is one password (for the master calendar) that can be used to change other calendars' passwords. But if you forget that password, you can reset it by editing calendars.xml: Find the spot that looks like this: <admin_password>[bunchofgibberish]</admin_password> Change it to: <admin_password>NaYFXtr6jHTe2</admin_password> That will reset your password to "12345", without messing up anything else. This assumes you have left your salt configured as NaCl - If you don't understand this igore it :-) Using mod_perlThis works on FreeBSD 4.11 with Apache 1.3 and Perl 5.8
\\ Note: I moved .pl and .cgi files into a cgi-bin directory under plans. Then I added aliases for the data, sessions and themes folders. Similar to what awstats does.\\ \\ UpgradingQuick & Easy upgradesEach [[release_notes|release announcement]] includes a list of what files have changed since the last release. You can replace just these files. Except if you're going from 6.X to 7.X. Too much has changed to make it practical to replace the files. Slow & Safe upgradesA more careful method is to install the new version of Plans in a parallel directory alongside the old one. This recommended for users who want the ability to quickly switch back if there are problems with a new version. Back up all the data onto your hard-drive first, before you do anything! 6.X -> 7.X upgradesTo upgrade from 6.X to 7.X, do the following: - Install a fresh copy of 7.X - Copy your calendars.xml and events.xml files into the data/ subdirectory of your 7.X install. - Edit the 7.X copy of calendars.xml, and replace the calendar passwords with 'NaYFXtr6jHTe2', like so: Before: ...<admin_password>dfigkYNlSf5z.</admin_password>... After: ...<admin_password>NaYFXtr6jHTe2</admin_password>... This will reset the password to '12345'. It's easiest to do this just to calendar 0 (the master calendar) and set the other passwords using the "calendar settings" tab. - If you're using a custom theme, get the latest version of that theme from [themes page]. If you customized the theme, you can keep your plans.css file, but you'll need the latest versions of the .js files.
Back up the data!Regardless of your method, always back up your events.xml and calendars.xml files before upgrading. Oh crap! The upgrade messed up my data!If your data gets somehow mangled (from an upgrade, or import or other calamity), [daltonlp@gmail.com email] your .xml files to the author, including a description of what's wrong (i.e. "all my events suddenly leaped 2 days into the past"). Diagnostic ModeFor troubleshooting, Plans has a "diagnostic mode" that lists (among other things) the settings from plans_config.pl. To activate this mode, point your browser at: %%http://your.domain.com/path/to/plans/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. Email remindersPlans supports email reminders, but this feature is turned off by default. To turn it on, do the following: - set the $options{email_mode} variable in plans_config.pl to 1 or 2 (see comments in plans_config.pl for what these numbers mean) - set up a cron job (unix) or a scheduled task (windows) to run the email_reminders.cgi script periodically. When a user requests an email reminder, Plans adds an entry to the email_reminders.xml file. When email_reminders.cgi runs, it reads email_reminders.xml and sends emails out for the entries in the appropriate time window. If your email is not being sent, your hosting provider may have anti-spam measures in place on the server. Be sure that you are using a valid email address for the From field. If it still does not work, check with your hosting provider for other things you may need to do to get outgoing email to work. SQL Database SupportThe 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. PrintingPlans 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)" Resource SchedulingA number of people use Plans as a simple resource scheduler, even though it's not designed to be one (Plans doesn't detect conflicts, and has no way to define "resources"). But it's easy to - for example - define a calendar for several conference rooms, and a "conference rooms" calendar with these calendars merged. If you do this, it usually helps to add the calendar title to what's displayed in each event box on the calendar. To do this, edit your plans.template file, and find the calendar item template:
<calendar_item>
</calendar_item> Add the ###calendar title### tag somewhere in this text, like so:
<calendar_item>
</calendar_item> CustomizingWhen you edit any of the config files, use a good text editor. Notepad is not recommended, [http://www.scintilla.org/SciTE.html|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###. ###special tags###Special tags you can use in the main section of plans.template
The plans.template file contains multiple templates. Below the main calendar template is are some more chunks of html which are templates for the event details pop-up window and each event's box on the calendar and list views. Special tags you can use in the <event_details> template section
Special tags you can use in <calendar_item> and <list_item> template sections
URL parametersIf you are constructing links to plans, the following parameters can be used. It's important to note that these are not a fixed API - they may change in future versions of Plans. |cal_id=of calendar to display|sets the active calendar for display or update| |diagnostic_mode=1|turns on diagnostic mode| |active_tab=1|sets the active tab (0=display, 1=event add/update, 2=calendar settings| IconsIf you want to add your own icons, you'll need: - three copies of your icon in your theme/icons/ directory If you'd like to contribute icons to the [Plans Icons Page], send them to the author ( daltonlp@gmail.com ). Integrating with your siteRemoving tabsIn plans_config.pl, you'll find the following text:
If you do this, you'll only be able to access the event and calendar editing pages by explicitly specifying the active_tab parameter in the URL:
Installing Plans on a Totalchoicehosting account |
Sign in to add a comment
Questions? Problems? Ask in the forum!
http://groups.google.com/group/planscalendar
(Don't post questions here - they will likely not be seen)