This is the installation and usage documentation for
AppIdeas.com's phpCommunityCalendar. Copyright and
distribution information can be found in the common.php
file in the main distribution directory. Technical support
is available at:
http://open.appideas.com

A brief overview of the features is available in the file
called "FEATURES" in the docs directory.

A change history is available in the file called "CHANGE"
in the docs directory.

#########################
## SYSTEM REQUIREMENTS ##
#########################
- A web server. Apache is preferred, but others will work
  with little modification.
- PHP 4 or higher. Features specific to version 4 are 
  incorporated into this package. With a little tweaking,
  you can probably get it working on earlier versions, but
  we don't recommend that.
- MySQL 3.23 or higher. Earlier version lack capabilities
  that are used in this package. If you use MySQL version
  3.22, their may be hope - see below.
########################
## RECOMMENDED EXTRAS ##
########################
- Perl 5 with DBI::mysql. This can be obtained from CPAN.
  Use of perl can aid in the task of removing events.

##################
## INSTALLATION ##
##################
This package should be fairly easy to install, and most can
get a functioning calendar system operational within a few 
hours.

The steps are as follows:
1) unzip and untar the package. On most *nix systems, this
   can be accomplished with:
   gunzip calendar.tar.gz
   tar xf calendar.tar
a) This will leave a directory called "calendar." If you
   need to use another directory name, unzip the archive
   outside of your web root, rename the directory and move
   it back to within the web root.
b) Underneath the directory above, you will have several 
   sub-directories. "admin" contains tools for the site 
   administrator. "webadmin" contains tools for category
   administrators. "tools" contains perl scripts for
   automated removal of events and an SQL data file for
   ease of database setup. The "images" directory contains
   images that are pre-installed with the calendar system.
   The "docs" directory contains documentation.

2) Move into the "tools" directory and create the database.
   This can usually be accomplished with the following
   command (assuming that you have a database already setup
   and that database is called "db_name"):
   mysql -h database.host.name -u database_username -p db_name < DB
   You will be prompted for a password and the contents of
   the "DB" file will be dumped into the database called
   "db_name"

3) Go to the main distribution directory and open the
   common.php file. You'll need to change the values for
   connecting to the database as well as the variables
   related to your server in the following section. The
   $glbl_WebRoot is relative to your web site's root
   directory. You will need to change the $glbl_WebAddress
   variable and might need to change the $glbl_WebRoot
   variable. You can probably leave the others alone.

4) Password protect your admin directory. In Apache, this
   can be accomplished through htpasswd by using a command
   similar to:
   /usr/local/apache/bin/htpasswd -c /path/to/passwd/file username
   Once you have supplied the password file, create a file
   called .htaccess in the admin directory and add lines
   like the following:
   AuthUserFile /path/to/passwd/file
   AuthName "Calendar Admin"
   AuthType Basic
   require valid-user
   Consult your web server documentation or ask your hosting
   provider for further help on this issue. Having this
   directory password protected is very important or else
   anyone can modify your calendar data!

Once you have completed the steps above, you are finished.
You will eventually need to do some of what's below, but at
this point, you should have a functioning system.

5) Go to your web site and into the calendar directory and
   admin subdirectory in a web browser. Enter your password
   and then click the "Modify configuration options" link.
   The options work as follows:
   - "Category types are called:" is a way to set what the
     web site displays as your categories to end users.  In
     other words, if your categories are "Departments" or 
     "Locations" you should specify the singular version of
     that word here.
   - "Web site title:" sets the text that appears in the
     title bar of your site visitor's web browsers.
   - "Truncate entries longer than:" sets the number of 
     characters that the web site will display in event 
     titles before truncating them for space conservation.
   - "Default view:" sets the calendar display that visitors
     are greeted by when they access the index page of the
     calendar.
   - "Site administrator's e-mail address:" sets the default
     e-mail address to use when another cannot be identified.
   - "Check to allow month/week/day view" when checked
     displays links on each calendar page allowing visitors
     to switch to the other calendar views.
   - "Check to allow printing of events" when checked
     displays a "Print" button on the event details screens.
   - "Check to allow public to submit events" creates a link
     on calendar view pages pointing to a page where members
     of the public can submit events to the calendar.
   - "Check to force approval..." when checked sets
     publicly submitted events to inactive until approval
     by an administrator.
   - "Public submissions approved by site/category admins"
     allows you to determine whether or not individual
     category admins receive notification of publicly
     submitted events requiring approval.
   - "Check to allow category admins to post..." when
     checked allows category admins to post events to other
     categories.
   - "Check to display location data..." when checked
     displays location information about events, as well
     as a link to a map to the location.
   Other features of the admin tools are (links on the main
   admin page):
   - "Events" The ability to add, modify and delete items
     to/from the calendar
   - "Event Addresses" The ability to add, modify and delete
     pre-defined addresses for inclusion in event location
     data.
   - "Categories" The ability to add, modify and delete
     categories (ways to separate sets of event data).
   - "Administrators" The ability to add, modify and delete
     category administrators.
   Category administrators can get to their own
   administration tools by entering into the webadmin
   subdirectory from a web browser.

######################
## OPTIONAL CHANGES ##
######################
6) If your directory is something other than "calendar"
   you will need to make a change to the .htaccess file in
   the main directory to reflect the name change. This file
   allows you to use your web aliases as direct links into
   calendar categories. In other words, if you gave a 
   category a web alias of "sports" you could access this
   category directly by going to:
   http://www.yourdomain.com/calendar/sports
   This will work on most systems, but some hosting providers
   will have disabled OverRide privileges. If your host is
   in this category, ask them if they will place the contents
   of this .htaccess file into your virtual domain
   configuration section of their web server config file.

7) To delete old entries automatically, you can run two 
   perl scripts from cron.  These are in the tools directory,
   but we highly recommend moving them outside of the web
   root before using them. The files are called
   "expireData.pl" and "expireSessions.pl" You will need
   to edit each of these files with the proper variables
   for connecting to your database. Once you have done that,
   you cn get them to process from cron with a command like:
   crontab -e
   Press "i" for insert and then type:
   0 1 * * *	/path/to/files/expireSessions.pl
   0 1 * * *	/path/to/files/expireData.pl
   Press "Escape" and then ":" and then "w" and "q" and
   then "Enter." This will add these files to cron to
   be processed at 1:00 AM every morning.

8) Common layout changes can be made in the common.php file.
   Place any layout HTML coding needed on the top of and to
   the left of the calendar within the commonHeader()
   containers and any HTML code neede for the right of and
   below the calendar within the commonFooter() containers.

9) If you are using version 3.22 of MySQL, you may be able to
   use the calendar by renaming some fields.  "DayOfMonth" was
   a reserved word in versions of MySQL prior to 3.23. This is 
   a field name in the Monthly and Yearly tables. If you change
   the name of those fields, the calendar should function properly.
   You will need to make this change in the tools/DB file as well
   as any scripts that make reference to this field name. If you
   are unsure how to do this, you can use any Windows word processor's
   search and replace functions. If you are using version 3.23 or
   newer of MySQL, you don't need to do this at all.

If you need technical support, please do not contact members
of AppIdeas.com's staff directly. A mailing list has been 
established as well as searchable discussion groups. They are
both available at:
http://open.appideas.com/

AppIdeas.com is available for installation and support of this
and other dynamic web site tools on a contractual basis. We
also have Unix system administration services available. For
more information, visit us on the web at:
http://www.appideas.com/

That is all.
