phpRecEvent README ------------------------------------------------------------------------------ What is it? =========== phpRecEvent is a web-based application to help you schedule and execute weekly recurring events. It consists of some php-scripts to create the user interface plus an (optional) cron-script written in perl to mail users the new event informations once a week. It supports per-event template files for both the interface pages and the emails which can be easily translated into other languages. Templates for English and German are provided. All HTML pages are customizable via CSS. Other features include grouping of participants, priority-based scheduling of the access of the web pages, auto-enrolling of some participants for the event every week, a mail messenger on the web pages and editing the template files via the browser. This software is freely distributable under the GNU public license, a copy of which you should have received with this software (in a file called COPYING). ------------------------------------------------------------------------------ Requirements: ============= For the web pages: ------------------ apache 1.3.x or better php 4 or better (tested with 4.1.1, doesn't work with 4.0.0 on OSF1 though) For the cron script: -------------------- perl 5 or better, plus the following perl-modules: + XML::Parser http://search.cpan.org/search?dist=XML-Parser + Time::ParseDate http://search.cpan.org/search?dist=Time-modules + Time::CTime http://search.cpan.org/search?dist=Time-modules + Mail::Mailer http://search.cpan.org/search?dist=MailTools + Unicode::String http://search.cpan.org/search?dist=Unicode-String Easiest way of installing those modules is by using the CPAN module that comes with the typical perl distribution: % perl -MCPAN -e shell cpan shell -- CPAN exploration and modules installation (v1.59_54) ReadLine support enabled cpan> On the cpan prompt use the 'install' command to download, configure and install the above modules, eg. cpan> install XML::Parser Note: This is usually done by the system administrator. If this is not the case for your machine, install the modules as normal user and read the docs on how to use modules in non-standard directories. (perldoc lib) ------------------------------------------------------------------------------ Installation: ============= In the following instructions you have to substitute VERSION with whatever version you downloaded, eg. 0.5.1, so phpRecEvent-VERSION.tar.gz means actually phpRecEvent-0.5.1.tar.gz. General: -------- 1) Unpack the tarball to temporary directory via: % gunzip < phpRecEvent-VERSION.tar.gz | tar xvf - or if you use GNU tar: % tar xvzf phpRecEvent-VERSION.tar.gz or use whatever tool you normally use to unpack tar.gz's. 2) Change to the new directory % cd phpRecEvent-VERSION 3) Check that the first line in both set_setup_password.pl and also cron/event_mailer.pl are containing the proper path to your perl binary. Maybe you'll have to change #! /usr/bin/perl -w to #! /usr/local/bin/perl -w or some other path depending on your environment. For the web pages: ------------------ 4) Set the master password for the setup.php script. Everyone who want's to set up new events needs to use this password to access setup.php. It is NOT needed for editing events though, which is only allowed for event administrators which are authenticated via their admin-password anyway. % ./set_setup_password.pl www/defaults.inc Enter setup password: Re-enter password : Password successfully set. % You can run set_setup_password.pl at any time to change the password for setup.php, just provide the location of defaults.inc as argument on the command line. 5) Copy the content of the www/ directory to a place below your document root, eg: % cp -r www/ /var/www/events or for example if you install it as a normal user: % cp -r www/ ~/public_html/events 6) Change into the new directory, eg. % cd ~/public_html/events 7) Edit defaults.inc and change the value of BASE_URL in defaults.inc to the address this directory can be accessed with in a browser, eg. define("BASE_URL", "http://your.domain.here/~username/events/"); IMPORTANT: BASE_URL has to end with a '/' 8) Make sure that the web server can write to the events/ directory. Either % chmod o+rwx events/ which will give everyone full access to the directory (not a good idea) or use chown / chgrp to change the owner / group of events/ to the user-id / group-id with which the web server process is running. Eg: % chgrp www-data events/ For the cron script: -------------------- 4) Copy the cron script to some other directory from which you want to run it, eg: % cp cron/event_mailer.pl /usr/local/bin/ or: % cp cron/event_mailer.pl ~/bin/ 5) Make sure that the script is executable. If you want all the users on your machine use the script: % chmod 755 /usr/local/bin/event_mailer.pl If you want only want to run the script yourself: % chmod 700 ~/bin/event_mailer.pl 6) Edit event_mailer.pl and change the following lines to your likings: my $from_address = 'someuser@somedomain.com'; Change that to an email address that should show up in the From: header of the outgoing emails. my $install_dir = '/home/spiney/public_html/events/'; Change that to the directory in which you installed the php scripts, see step 3 in the web pages installation. my $work_dir = '/home/spiney/.event_mailer/'; Change that to a directory which will contain the working data of the cron script. The directory will be created if it doesn't exist. 7) Add a new job to your crontab, e.g. first run % crontab -e and while editing your crontab add a line like the following: 10 * * * * /use/local/bin/event_mailer.pl The above example runs the script once every hour, always 10 minutes past the full hour. You can adjust the time, but make sure that the script runs at least once an hour so that the mails are sent at the proper times. IMPORTANT: Be sure to change the paths in the example to your environment! ------------------------------------------------------------------------------ Usage: ====== 1) Point your browser to BASE_URL/setup.php, enter the master password and set up a new event. 2) Mail the username and user-password to each of your users. 3) Remember your admin-password. Don't write it down. Remember it. ------------------------------------------------------------------------------ Feedback: ========= Please send any comments, suggestions or questions to spiney@spiney.org Patches for bugfixes or feature enhancements are also welcome. ------------------------------------------------------------------------------ Todo: ===== See the TODO File for things that are still to do and are planned for future releases. ------------------------------------------------------------------------------ Bugs: ===== See the BUGS file for known bugs, and report any new ones to spiney@spiney.org ------------------------------------------------------------------------------ Website: ======== http://www.spiney.org/public/phpRecEvent/