a cgi library to keep your website updated while you sleep
If you have a website that needs to be regularly updated because you have regular events displayed on your homepage, then events is the tool for you. events originated rom a web page of a service in our congregation, where we needed to display the date of the next service on the homepage and I just hated to update the page just because of the new date.
events helps you to speed up this process. After putting all the dates into one text file, you're able to display a list of all events or just the next one or today's event. You could use it to display a Motto-of-the-day (or of-the-week), a birthday list, a list of the next events you're going to speak at or much more.
events consists of a library and some scripts which offer different output capabilities. The scripts are thought to be used in a SSI-Environment, but it also makes sense to use them to display a frame.
If you're not satisfied with the possibilities you get with events, you can customize the scripts. If you have some perl programming skills, you can easily a script customized to what you need. All functions are packed into one perl library, eventlib.pm.
I only ask that you distribute the package unmodified. If you have found a bug or know of something I could enhance, please contact me at events-feedback@web42.com. Maybe you have even written a script which is worth being distributed together with the package?
To use events, you need a web server running a UNIX(tm) system with the ability to execute CGI scripts and Perl 5 installed. Sever-Side-Includes are not actually a must, but events runs best with SSI.
events has only been tested on Apache Servers (on Linux and FreeBSD).
events hasn't been tested on Windows NT Systems, but could probably used on it with a few modifications.
Installing events is easy. To use events, you must be able to run CGI scripts on your host.
Untar/Unzip the distribution file (using tar -xzvf events-1.00.tar.gz). You will get the following files:
readme.html this file events.shtml a sample html file which calls some scripts via SSI events.txt a sample events file cgi-bin/eventlib.pm the library which contains the important functions cgi-bin/event-test.cgi a test script to make sure everything's working cgi-bin/event-next displays the next event cgi-bin/event-today displays today's event cgi-bin/event-list displays a list of all events cgi-bin/event-list-past displays a list of all past events (including today) cgi-bin/event-list-future displays a list of all future events (including today) cgi-bin/events.txt a sample events file Put all the files in the cgi-bin subdirectory in the directory where you run your scripts from (it's probably called cgi-bin, too).
Make sure the scripts are all marked as executable (using chmod 755 events* in the directory you placed the scripts in).
To test if everything is working, you should run event-test.cgi (by leading your browser to http://www.yourdomain.com/cgi-bin/event-test.cgi/. You can also use events.shtml to check the scripts (note that it depends on the scripts being in /cgi-bin and uses Server-Side Includes).
After testing, you can move cgi-bin/events.txt to another directory and create your own events.txt (see Setting up your events.txt).
If you run into problems, take a look at the Common Problems section
I have tested events only on two webservers so far, so you probably may run into some problems.
If event-test.cgi doesn't work, then try to execute it from the command line.
If you get an error like "Permission denied", you probably forgot to use chmod to mark the scripts as executable (see Installation).
If you get an error like "No such file or directory", make sure you have perl 5 installed as /usr/local/bin/perl. If not, then you'll have to change the path to perl in the scripts and also in eventlib.pm.
If event-test.cgi works well, but the other scripts won't (they're displayed like text files in the browser instead), then your server probably can't handle scripts with no extension. Try to rename them to .cgi.
If the scripts run well, but output nothing and you uploaded your scripts from a different OS (Mac, Windows) to your Unix box, make sure the linebreaks in the events.txt are UNIX-like (it seems to be a little bit far-fetched mentioning that, but - been there, done that ;-) ).
If you can't solve your problems this way, feel free to contact me at events-feedback@web42.com.
To use events, you'll have to set up a text file containg all the events you wish to display on your pages. This file will be called events.txt in most cases.
You can call the scripts using two different approaches:
1. You can call them embedded into another document, i.e. using SSI. You could for example call them using <!--#exec cgi="/cgi-bin/event-next"-->. Used this way, the script will look for a file called events.txt in the directory where the document calling the script is stored in. This is the most useful way of using events.
2. You can also call them directly, for exampling by including a link like <a href="/cgi-bin/event-next"> in a HTML document (or use it as a frame). This way, the script will look for a file called events.txt in the directory where the script is stored in. You can change this behaviour by supplying additional path information with the link, e.g. <a href="/cgi-bin/event-next/friends/birthdays.txt">. The script will now look for a file called friends/birthdays.txt. SSI don't allow the use of this additional path information.
Okay, after talking about where to place the file I should probably explain to you what to put into it.
An event file consists of different sections and can be compared to a Windows .INI file. The order of the sections doesn't matter. events will ignore any lines starting with a hash sign ("#") and empty lines, so feel free to comment and structure the file as you need to.
Here's the sample events.txt supplied with the package:
# Sample events.txt file [config] # Configure timezone # 2 means GMT+2 # -3 mean GMT-3 # No entry means use local time timezone=2 [templates] # default template. Used to display the next event default: <p align="center"> <font color="FF0000"><strong> [title] </strong></font><br> [desc]<br> # list template. Used to display a list of events list: <tr> <td><strong>[title]</strong></td> <td>[desc]</td> </tr> # notfound template. Used if no next event was found notfound: <strong> I'm sorry, nothing special is ahead! </strong> [events] # Use the German date format... 01.01.98: title=January 1st: New Year desc=Hooray, this is the first day of the year! # Or the American date format 07/01/98: title=July 1st: 1998/2 desc=Gosh, half of the year's already gone! # And mix them as you like, just don't forget the trailing ":" 06.12.98: title=Dezember 6th: St. Nicholas day desc=Watch your chimney this night... # This is a special one... 01/17/99: title=January 17th: My 21th birthday! desc=Send congratulations to crenz@web42.comAs you can see, there are three different sections: the [CONFIG] section, the [TEMPLATES] section and the [EVENTS] section.
5.1 The [CONFIG] section
This section is pretty small. It contains variables in a name=value format.
At the moment, there is only one (optional) variable called timezone. I included it because my webserver is in America (GMT-5), whereas I live in Germany (GMT+2), which means a difference of 7 hours. Since I am planning to include time information as well, this variable can be important. Set it using timezone=2 or timezone=-3, or even timezone=0 to use GMT. If you omit the variable, the local time of your webserver is used.
5.2 The [TEMPLATES] section
As you will see later, you supply variables such as title, date, description with an event. You can use templates to display this information in a specific format.
There are three standard templates, called default, list and notfound. The default template is used when you are displaying a single event, using event-next or event-today. The list template is used for displaying multiple entries, for example using event-list or event-list-future. The notfound template is used when you're using event-next and there is no event in the future. You can use other template names when you're customizing the scripts.
A template consists of one header line containing the template name, followed by a colon, and one or more text lines indented with at least one whitespace. You can insert variables using brackets, eg. Hi! Today's <strong>[friend]'s</strong> birthday!<br>Go buy <em>[present]</em>!. If you have defined an event using friend=Sandy and present=a pair of socks, this will result in Hi! Today's <strong>Sandy's</strong> birthfay!<br>Go buy <em>a pair of socks</em>!.
If you would define the template in the events.txt, it would look like this:
[templates] default: Hi! Today's<strong>[friend]'s</strong> birthday!<br> Go buy <em>[present]</em>!A hint to avoid mistakes when creating a list:
You will probably think of using a table to display a list of all events. When you're doing it, it should be in a form like
[templates] list: <tr> <td> [friend] </td> <td> [present] </td> </tr>You shouldn't forget to use a bracketing <table>...</table> in the .shtml file calling the script, like in
<table> <tr> <td> My friend's name: </td> <td> My present for him </td> <tr> <!--#exec cgi="/cgi-bin/event-list-future"--> </table>5.4 The [EVENTS] section
This section contains all your events. You can use either the German or the American date format to define them. The event of the above example would look like
[events] 27.07.98: friend=Sandy present=a pair of socks 07/28/98: friend=Sandy's brother present=a smack in the head ;->Regardless of which date format you use, events will translate it in the internally used yymmdd format.
6. Bugs
When you reference a variable in a template which is not defined in the event used, it will just stay there and appear on the screen, like in Today's Sandy's birthday. Go buy [present], assuming that only friend, but not present was given when defining Sandy's birthday. A better solution would probably be to delete this reference.
Because of using the yymmdd date format, events actually isn't Year-2000-compatible (it will think that the events in the year 2000 are earlier than the ones in 1999). I intentionally left that in to show the people the grave dangers of Non-Year-2000-compatible applications :-) (of course, sure, we believe you, no, you weren't too lazy to do it, of course not...)
If you notice other bugs, please contact me using events-feedback@web42.com.
7. TO-DOs
There are some things I already thought of and I'll probably implement them as soon as I have time for them.
One thing is writing other scripts, like "display the next five events". I'll do that as soon as I need them (or as soon somebody asks me to do it).
Another thing would be to include time information in the events to be able to display a certain event at a certain time.
The highest priority at the moment has including events with no year given, which would be useful for birthdays etc. You could supply only "07/03" and events would automatically insert the current year for you.
8. Downloading the newest version
The home of the events package is http://www.web42.com/scripts/events/. You'll find information about new releases there. You can download events from this location or using FTP from ftp://ftp.web42.com/scripts/events/.
Please notify me when you're using it because I'm interested in how many people use events and what for. You'll also be notified of updates via e-mail, if you want to.
9. License
events - which means the files mentioned in Installation - is Copyright (C) 1998 Christian Renz.
You may use events as is, without any warranty, for any kind of commercial or non-commercial application. You may distribute it in the original form as available from ftp://ftp.web42.com/scripts/events/ without charge. Feel free to tailor the software to your needs, but you may not distribute a changed version of events.
I would delighted if you would credit me if you're using events, e.g. with a sentence like "This site uses the events package for displaying up-to-date information", but this is no condition to use events.
10. Conclusion
I developed events primarily for my private use - you'll find it doing it's work on http://www.web42.com/online/ (in German only), which is the homepage of a service we're having in our congregation.
I decided to make events public because I am using a lot of public domain packages myself. I'm trying to give something back to the net community through my work.
I hope that this package is useful for you and will serve your needs.
It is the first time for me to release a program into the public and also my first major programming project in Perl. Please be forgiving if I made any errors and tell me of them.
Christian Renz
Last updated: 20.07.98
http://www.web42.com/events/scripts/