This document was written to share my experience with using the two scripts described here. It is primarily a reference for myself. I am making it available for others as a way of paying back all of the help I have received online, at local computer user groups meetings, and face to face from other computer users. Constructive criticism, corrections, and improvements are welcome.
Important: Back up your entire site before modifying any files or installing any new scripts. This information comes with no warranty, guarantee, or assurances of any kind. Use at your own risk.
I wanted to have a dynamically generated calendar on my website. I already used Coranto for other dynamic content on the site. I wanted items that were entered using Coranto to display on the calendar and in other news pages, without entering the information again using another script. This document describes the solution I found. It does not give detailed information about installation of either script used.
I am using this setup at: SSC Softball Calendar
For Coranto support use the Coranto Forums.
Comments about this document can be sent to: Dale Ray.
Coranto is a perl script used to create and edit news that is presented on your web site. Coranto resides on your server and provides a web interface to edit your site from any browser.
smcCal is a perl script that generates a calendar from a text file. smcCal is also a server side script. The script itself and the file it reads reside on the server. The feature lacking in smcCal is a web interface to edit the data file that is used to store the events.
This document explains how to use Coranto to provide a web interface to smcCal and use smcCal to display your Coranto items in a calendar format.
Both of these scripts are free to use. You can find out more information about each and download them at:
You must have Coranto and smcCal Cal both installed and working. Both scripts have installation instructions with them. If you want to specify future dates and times you will need the ChangeDateNew addon for Coranto. It is available on the addons page at the Unofficial Coranto Website.
Note: If you do not use or want to use the ChangeDateNew addon to set the date and time of your event you can create custom fields in Coranto. For the date you could create:
You can use any type of field you want, but a drop down list will make sure that the values entered are valid. Use 01 thru 31 for the days, 01 thru 12 for the months, and however large a range you want for the years. Remember to include 0000 as an option for the year (this will let you enter recurring events only once, see the smcCal Docs). You can apply similar logic if you wish to show times.
This idea suggested by nuggetman, in the Coranto forums.
When you install smcCal write down the location (the path, not the URL) of the data file. You will need this information to configure Coranto. smcCal includes a test data file in the archive, use the test file to make sure the calendar is working.
The remainder of this document assumes that both scripts are working.
We are going to create a style that will write your news into the correct format for smcCal to read and display. We are creating the style first so that when we create a profile later we can set all of the profile options in one step.
Data File Format
To create the style you must understand the format of the data file used by smcCal. Data for smcCal is stored in a delimited text file. Each item that you want to display on the calendar is stored on one line in the data file. Each line has the format:
date^textcolor^bgcolor^event^url^popupmessage
The separator that is used by default is the caret (^), but you can change the smcCal script to use whatever character you wish. Let's look at each item on the line.
Some notes from the smcCal docs:
Of course you read the smcCal docs completely when you installed it!
So now that we understand the format we can create Coranto style that writes this file for us, using our existing news files. There is some info you will need.
For this example we will assume a simple profile that uses only the default subject and text fields in Coranto. The subject will become the event text shown on the calendar and the text will be displayed using Coranto's viewnews.cgi when the event is clicked.
Style Example
<Field: Year><Field: TwoDigitMonth><Field: TwoDigitDay>^^^<Field: Subject>^<If: Field: Text>http://www.yoursite.com/cgi-bin/coranto/viewnews.cgi?id=<Field: newsid>&style=yourstyle</If>^
You want to enter that on a single line and then a return at the end so that the next news item is written to a new line.
<Field: Year><Field: TwoDigitMonth><Field: TwoDigitDay> writes the year in the proper format
The three carets ^^^ represent the end of the date, and that there is no textcolor or bgcolor specified for this item. You can set these to whatever you want.
<Field: Subject>^ prints the subject of your news as the event text that is shown on the calendar grid and the end delimiter.
<If: Field: Text>http://www.yoursite.com/cgi-bin/coranto/viewnews.cgi?id=<Field: newsid>&style=yourstyle</If> ^ will make the event text a link ONLY if the text field is not empty and prints the caret to denote the end of the url.
This is a very basic example. There are more examples and discussion of some other things you can with Coranto and smcCal later in the document.
Top of PageThe filter settings:
Can be set to whatever values you wish.
You are now ready to build news. The test data file that you installed to test smcCal should be over written by the file that Coranto creates. Call the smcCal script from your browser and the events from Coranto should be displayed.
Here are some things to look at if your setup isn't working:
If Coranto wrote the data file and the format is wrong, check your Coranto style.
If Coranto did not replace the test data file and there was no error, check the path you entered into Coranto and check that the file didn't show up somewhere you didn't intend.
Here are some more ideas for using Coranto and smcCal together.
As written smcCal does not provide for multiple calendar support. To add this functionality you must make changes to the index.cgi file. Since all of the calendar parameters are contained in the config.pl file it seemed easiest to allow multiple configuration files. Each file has the parameters for one calendar. We will pass the name of the config file to smcCal as part of the URL when we call the calendar.
Top of PageNOTE: I am NOT an experienced perl programmer, if you can suggest improvements to this modification they are welcome. Make backups and use this mod at your own risk.
I modified index.cgi, which is the main script powering smcCal to allow multiple calendars.
This is the original lines 27 thru 29 of index.cgi:
&checkForErrors;
&initializeVars;
&readCalendarData;
The initializeVars subroutine reads the parameters from the url and the checkForErrors subroutine uses the name of the config file. I swapped line 27 and 28 so that the variables are initialized before the error checking routine.
&initializeVars;
&checkForErrors;
&readCalendarData;
Line 47, in the checkForErrors subroutine has to be changed to use the config file name passed with the URL
my $libfile = 'config.pl';
becomes
my $libfile = $config.'.pl';
Lines 80 thru 82 read the parameters from the url.
&getOptions(*FORM);
$option = $FORM{o};
$style = $FORM{s};
Here is what I added to this subroutine, directly following the lines above:
# add reading of config file name from url
$config = $FORM{c};
# default to config.pl if no value in url
if ($config eq "") {
$config = "config";
}
To make the forward and backward navigation work you have make some changes in the section labeled "Print the top of the calendar table." Find the line that reads:
$prev = "<a href=\"${thisurl}?mm=$prevmm&yyyy=$prevyyyy\" "
and change it to:
$prev = "<a href=\"${thisurl}?c=$config&mm=$prevmm&yyyy=$prevyyyy\" "
You must also change the line that reads:
$next = "<a href=\"${thisurl}?mm=$nextmm&yyyy=$nextyyyy\" "
to
$next = "<a href=\"${thisurl}?c=$config&mm=$nextmm&yyyy=$nextyyyy\" "
This adds the name of the config file to the URL that the arrows refer to.
You can now pass the name of your config file as part of the URL. If there is no config filename passed it defaults to config.pl.
Note: For each calendar that does not use the standard config.pl file you must set the calendar header option to not display the navigation form in the calendar header. Each time you use the form for navigation it displays the calendar with the default config file. If you can help with a fix for this let me know.
Top of PageFor each calendar you want to use you must create a configuration file. The file must have the file extension .pl and it must be in the same directory as index.cgi. By duplicating the entire configuration file you can control all aspects of each calendar.
I use the default config.pl for my calendar that includes all events from all profiles. This is a master calendar. You can add navigation to the individual calendars to the header or footer files that smcCal uses.
Call smcCal with the format:
http://www.yoursite.com/pathtosmccal/index.cgi?c=yourfilename
So to use a non default configuration file you simply add the ?c=yourfilename at the end of the URL. You can chain the c=yourfilename with other allowed parameters. When passing the configuration file name omit the .pl extension.
In Coranto define a profile for each unique calendar. In your smcCal configuration file for the calendar define the path, data filename, and any other options you want to set for that calendar. When you call smcCal with the proper configuration filename your data will be displayed.
smcCal allows you to include a custom header and footer on your calendar page. If you use Coranto's template editor addon you can edit these with Coranto by changing the filename extension to .tmpl and putting them in your Coranto directory with your other templates.
Let's name the header cal_header.tmpl and the footer cal_footer.tmpl. You can create these offline and upload them to your server or create them with the template editor addon.
After you create the header and footer edit the config.pl file for smcCal and set these variables to the path to the files:
$header = '/thepathto/cal_header.tmpl';
$footer = '/thepathto/cal_footer.tmpl';
Now if you need to update the calendar header or footer from a remote site you can use any browser to access you Coranto installation and edit them.
smcCal can be used to include a list of the current month's events or a list of the next X days of events as a SSI call. The call takes the form of:
<!--#include virtual="/cgi-bin/cal/index.cgi?o=list&s=current"-->
The s=current tells smcCal to include the current month's events on the page. There are limitations to this that are explained in the smcCal documentation.
If you change s=current to s=days14 smcCal includes the next 14 days events.
Using either form will display the events in a table. You have to modify the script to display the events in a different form. Here is the code from smcCal that displays the next X days as an include:
# *************************************************************** #
# * Print events for the next x days only Table Form * #
# *************************************************************** #
elsif ($style =~ /^days(\d+)$/) {
$days = $1;
$today = $today_yyyy . $today_mm . $today_dd;
$lastdate = &dateadd($today_yyyy,$today_mm,$today_dd,$days);
print "<!-- Printing events from $today to $lastdate -->\n";
foreach (@caldata) {
($ndx,$date,$txcolor,$bgcolor,$title,$url,$msg) = split(/\Q$sep/);
next unless (($date >= $today) && ($date <= $lastdate));
$yyyy = substr($date,0,4);
$mm = substr($date,4,2);
$dd = substr($date,6,2);
$dd -= 0;
$dndx = &dayofweek($yyyy,$mm,$dd);
$date = $weekdays[$dndx] . ', ' . $months[$mm - 1] . ' ' . $dd;
if ($msg ne '') {
$url = "javascript:msgAlert(${ndx})";
$msgs[$ndx] = $title . '\n' . $msg;
$msgs[$ndx] =~ s/<br>/\\n/g;
$msgs[$ndx] =~ s/'/\\'/g;
$jsmsgcnt++;
}
$title = "<a href=\"$url\">$title</a>" if ($url ne '');
print "<tr>\n",
"<td class=\"smc\">$date</td>\n",
"<td class=\"smc\">$title</td>\n",
"</tr>\n";
$lcv++;
}
unless ($lcv) {
if ($days == 0) { $msg = "No events for today."; }
elsif ($days == 1) { $msg = "No events for today or tomorrow."; }
else { $msg = "No events for the next $days days."; }
print "<tr>\n",
"<td class=\"smc\" colspan=2 align=center>$msg</td>\n",
"</tr>\n";
}
}
I am not a perl programmer but it look like elsif ($style =~ /^days(\d+)$/) is checking for the style parameter. We can duplicate the function and edit it to present the events as we like.
Find this code
print "<tr>\n",
"<<td class=\"smc\">$date</td>\n",
"<td class=\"smc\">$title</td>\n",
"</tr>\n";
Now use this <!--#include virtual="/cgi-bin/cal/index.cgi?o=list&s=mystyle14"--> to include the events in another page. You can use any name you want for your style and do more than one if you want. You can specify the number of days you want in the SSI call.
Why use smcCal instead of Coranto to include your event list?
These are ideas that I have not tested, but should work.
Exclude Some Items
If you have a category of news that you want to include in the calendar, but there are a few items you wish to exclude you can create a custom news field and use that to check in your style. Example: create a custom news filed called calendar, make it a checkbox, set it to be on. When you add or edit news if you want to exclude the item from your calendar uncheck the box. In you style add an if statement that looks like:
<If: Field: CustomField_calendar>rest of your style code here</If>
You can default the checkbox to cleared if you want to exclude most of the items in a profile. You can also turn an event off temporarily using this technique.
More Suggestions
Recurring Dates
smcCal allows you to post recurring events, such as holidays without entering them for each year. It does this by using a year of 0000. The ChangeDateNew addon or some other internal working of Coranto does not allow for the year 0000 to be entered. You can modify smcCal to check for another year that Coranto and ChangeDateNew does allow, such as 1969 or you can add a custom news field to indicate an annual event and test for that in your news style.
You can also add a custom newsfield of the checkbox type and check it for recurring events. In your style you can print the 0000 required by smcCal for recurring events if the field is checked.
See the note above for another way to implement smcCals's recurring event support with Coranto.
Author: Dale Ray
Original Published - August 11, 2003
Revised - August 17, 2003
Removed extra spaces in Coranto style example
Revised August 18, 2003
Added alternate method to publish event dates
Revised August 25, 2003
Added directions for using multiple calendars.
Added suggestion for writing year for recurring events.
Revised September 10, 2003
Updated multiple calendar navigation information
Added note about using the navigation forms in multiple calendars
Other minor revisions and changed the order of some sections.
Added Legal Information
Revised - November 13, 2003
Moved document loaction to Coranto Demo
Added links to Coranto Demo Homepage
This document copyright September 10, 2003
This document is copyrighted by the author, Dale Ray. It may be reprinted and/or reproduced for non-commercial, non-profit use only. You may not reprint and/or reproduce this document in any form for profit or for use in a venture that is operated with the intent of making a profit without the author's permission. You must leave this copyright notice intact. If you alter the content of the document you must clearly indicate the altered sections.
If you reproduce this document I ask that you contact me and let me know where and how you are using it.
No warranty, promises. or guarantees
The information in this document is accurate to the best of my knowledge. Use this information at your own risk. Make back ups and back ups of your back ups. There are no promises or guarantees of the fitness of this information for any use. There are no implied or stated warranties.
Thanks
My thanks to Scott M. Crevier, the author of smcCal for the gift of the smcCal script to the internet community.
I also want to thank those in the Coranto community for the development and maintenance of Coranto.