|
smcCal is a web-based calendar program. It displays a nicely formatted, easy to
read calendar on a web page, driven by a simple text file containing the calendar
events.
Feel free to take a look at my live sample calendar.
This program is quite suitable if you are responsible for scheduling office events, maintaining personnel schedules or publishing sports calendars. It also makes a great resource for your busy family; just put all your events on your family web site, and you can view it from anywhere (at home, at the office, friends house, etc.).
Maintenance of the calendar is quite easy, and when your colleagues or web site visitors view the calendar, it always reflects the very latest data.
Full instructions follow.
Requirements:
This script has been fully tested and should work fine in most UNIX environments, with a recent version of Perl.
I have not used it on a Windows machine, but if you're familiar with a Windows-based web server, you should
be able to get it running.
To install smcCal:
- Download the tar file from the scripts page.
- put the download file in a directory on your web site
- untar it with the following command:
tar xvf smcCal.tar
This will create a new directory called 'calendar' which contains everything you need. The current file permissions should be okay on most web sites.
- The calendar along with sample event data is now ready to run. Just go to the URL that corresponds to the new calendar directory.
For example, if your web site is at www.yourcustomname.com, and you untar the file in your root directory, then the URL of
the calendar will be:
www.yourcustomname.com/calendar
Here are the files included with the smcCal program:
- index.cgi
- This is the main CGI script that runs the calendar. You can change the name of this file if you want. This file must be executable. A permission setting of 705 should be sufficient for most web sites. If you're not sure how to set the permissions, the following command should work on most accounts:
chmod 705 index.cgi
- config.pl
- This is the main configuration file. This file is new in version 2.0. All customizations can be made in this file. It's important to note that this file is a true Perl library, and as such, syntax must be accurate. So, I highly recommend that you keep a backup copy of this file before making any changes. That way, you can always refer back to it if you need to. If you're not an ace Perl programmer, don't worry, the settings in this file are very easy to understand. Documentation for the possible customizations is included in the comments of the file.
- dates.txt
- This is the main calendar configuration file.
This is the file that you will maintain to control what appears on the calendar.
Each line in the file represents one event on the calendar. The syntax of each line is as follows:
date^textcolor^bgcolor^event^URL^popup_msg
- Where:
- date is the event date in yyyymmdd format
- textcolor (optional) is the color that you want the text to be on the calendar. Any valid HTML color is legal. For example, 'red', 'green', '#000000', etc.
If no textcolor is specified, then the text color for this event will default to the text color from the <body> tag as indicated in the 'head.htm' file (see below).
NOTE: Be advised that if a URL is indicated (see below), then this text will be an active link, and support of this textcolor then depends on the browser. For example, Netscape Communicator 4.0 will honor this color setting, while Microsoft Internet Explorer 4.0 will not. If there is no URL, then this color should work fine.
- bgcolor (optional) is the background color for that date. Like the textcolor, any valid HTML color is legal. If multiple events on the same date have different bgcolors, then the last one wins.
If no bgcolor is specified, then the background color for that date will default to the background color from the <body> tag as indicated in the 'head.htm' file (see below).
- event is the actual string that will appear on the calendar.
- URL is an optional URL that the event text should link to. This can be the full URL to a separate web site, or a relative URL on your web site or even a link to an e-mail address. Here are a few examples:
- http://www.webmaster.crevier.org/
- /contact/
- mailto:scott@crevier.org
- popup_msg is an optional text string that will display in a popup box (via JavaScript) when the event is clicked on.
- Here are some further rules/suggestions for the 'dates.txt' file:
- The event text on the calendar can only have one link. So if you indicate a URL, then you should not have a popup_msg; and vice-versa. If you happen to indicate both, then the URL will be ignored.
- If you have an event that happens every year (like New Year's Day or your wedding anniversary), you can indicate that by entering '0000' for the year. Then you don't have to re-enter it for each year. For example, the date for New Year's Day would be '00000101'. The included events file already contains many annual holidays.
- Events can be in any order in this file. If there are multiple events for a single date, they will appear on the calendar in the same order that they appear in this file. For example, if you want all holidays to appear above other events on the calendar, just list them first in this file.
- Since the date is the first field on each line, all event lines must begin with 0, 1 or 2. '0' for an annual event, '1' for the 1900s or '2' for the 2000s. Therefore, ALL other lines are ignored.
- If you want to put a bullet before each event (which is handy if you tend to have many events on the same day), just type • at the beginning of the event text.
- The live sample calendar referenced above uses this live dates.txt file.
- right.gif
left.gif
- These are the images that serve as the navigation arrows. When a user clicks on the right arrow, they go to the next month. When they click on the left arrow, they go to the previous month. You can substitute your own arrow images. Or you can move these images to your current images directory, then change the 'config.pl' file accordingly. Or if you already have your own arrows, just delete these two files, and change the 'config.pl' file accordingly.
- head.htm
tail.htm
- These HTML files indicate what should appear on the web page above and below the calendar. The 'head.htm' file is especially important as your settings in there will determine the color of the web page, the text color, the page title, etc.
- sample.shtml
- This is a sample HTML page that shows how you can use the server-side include features of smcCal. See below for an explanation of the server-side include.
- Server-Side Include Options:
- This calendar script can also be called as a server-side include. A good use of this feature is if you want to display a small table on your web site's front page, to list only this month's events. There are several ways to use this feature.
First of all, if you're not familiar with server-side includes, you should be. SSIs provide a very simple but powerful way to add interativity to your web site; and most UNIX-based web servers support it. You can read more about this on my Server-Side Includes page. The key point to realize is that most configurations will require your HTML file to be named with the ".shtml" extension, instead of ".html".
Some web servers may not support server-side includes. Others may support server-side includes but may not support the "include virtual" method that is described below. The "include virtual" method is required (versus the "exec cgi" method) in order to pass arguments to the script. If your web server does not support this, then you won't be able to use this particular feature. Sorry.
Now, when using this feature, it's important to know that the script will only generate the HTML code for the table rows. It does NOT generate the beginning <table> tag or the ending </table> tag. This means that you need to define your own <table> tag, which will control the look and colors of the table. Also, the script displays the table cells using a style that I arbitrarily name 'smc'. This is so that if you're familiar with style-sheets, then you can use them to define the look of the events table. Be sure to see the 'sample.shtml' file which is included with the package. It contains several good examples that you can just copy and paste into your own HTML file.
Now, let's get on with the the syntax. You can use one of several different options to display the calendar events in different formats.
The first option will display all events for the current month. So, if today is May 2, you'll get all of May's events. If today is May 23, you'll get all of May's events. If today is June 12, it will display all of June's events. This option may not be appropriate for some web sites, as it will display events that have past. For example, if today is the last day of the month, most events for the current month will have already past. But if this option will suit your web site, then use the following syntax:
<!--#include virtual="index.cgi?o=list&s=current"-->
The second option will display all future events that will occur within the number of days indicated. The nice thing about this feature is that it will never display events that have past. So, for example, if you've got an event every day, this option will display a different table every day. Old events will automatically fall off and new events will be added each day. The syntax for this option is this:
<!--#include virtual="index.cgi?o=list&s=days30"-->
The above example displays all events for the next 30 days. You can put any integer in place of the '30'. So if you want events for the next month, use '30'. If you want events for the next 6 weeks, use '42'. If you want events for the next 6 months, use '180'. If you want only today's events, use '0'.
Be sure to see the 'sample.shtml' file, which is included with this package. It contains some good examples that you can copy and paste.
- Note to Users of Previous Versions:
- If you've used previous versions of this script, there are several things you should know.
- Be sure to check out the 'header_style' option in the 'config.pl' file. This option allows you to use the drop-down boxes for selecting the month and year.
- Previous versions used the semi-colon as the default separator in the events data file. I'm now using the caret (^) as the separtor. You can change this in the 'config.pl' file if you want.
- Previous versions had the text color and background color in the same field. These have now been split to two separate fields.
- Revision History:
- 1.0 — 1997 — This was the original version, which included the following features:
- Calendar display in typical calendar format.
- Navigation buttons to go to the next month or previous month.
- Simple text file containing calendar events.
- Optional text and background colors.
- Optional URL to link the event name to another web page.
- 2.0 — June 2, 2001 — This was the first major rewrite of the script. Enhancements include:
- Added optional month and year selection by drop-down boxes.
- Added the ability to have event notes display in a pop up (JavaScript) box.
- Added the ability to display event dates in a table.
- Moved the configuration options to their own config file. This makes it much easier to customize the behavior.
- Perl source code was completely rewritten. This is not too important to most users, but if you're learning Perl, the new source code format will be much easier to understand than the old one.
- Fixed button link location for servers that don't support "index.cgi" as a default. (Thanks David Melville, The Phoenicians Chorus)
- Several small bug fixes.
- 2.1 — June 2, 2001
- Minor fixes of bugs introduced in version 2.0.
- Added standard holidays through 2005 to the included events data file.
- Future enhancements:
- I'm working on a new web-based events maintenance script. This will allow you to maintain the calendar completely from the web.
- If you have any ideas, let me know.
- Maintaining the Calendar:
-
It has always been my plan to provide you with another script that will allow you to completely maintain
your events data, via a web page. While I do have the script written (and in use on a few sites), I
just have not had the time to clean it up and make it so that it will work well on other web sites.
So, for now, you have to maintain the data file yourself.
However, there is another similar program out there program called Coranto. And smcCal user, Dale Ray, has figured
out how to use the editing features of Coranto to maintain his list of events that are displayed via smcCal.
Dale has written up his instructions on the following web page:
Using Coranto and smcCal to Display an Event Calendar
I have not used Coranto, so I cannot vouche for how well it works, but Dale tells me it works very well.
Thanks Dale!
- Other Notes:
- When you first go to the calendar URL, the calendar will default to the current month and year. You can then click on the arrows to navigate forward or backward through the months. You will also notice that as you navigate, the month and year are indicated in the URL of the page. If you want to go directly to a specific month, just modify the URL accordingly. You can also use the 'header_style' option to turn on the month and year selection boxes.
- Live Users:
- Here are some web sites using the smcCal calendar program. If you're using this calendar, be sure to let me know and I'll add a link to it here:
|
