Using Coranto and smcCal to Display an Event Calendar

Introduction

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.

For Coranto support use the Coranto Forums.

↑ Contents

The Scripts

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:

Implementation

↑ Contents

Before You Start

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 from Parahead's Coranto Corner.


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:

  • CustomField_Year
  • CustomField_Month
  • CustomField_Day

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.

Making The Connection

↑ Contents

Create a Style

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.

↑ Contents

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.

  • date - must be in yyyymmdd format
  • textcolor - the color you want the event text to be. Names such as "blue" or hex numbers such as "#000000" both work.
  • bgcolor - the background color for the cell that the date is in. Same rules as textcolor.
  • event - The event you want to display
  • popupmessage - a message to display in a java popup when the cursor is over the event

Some notes from the smcCal docs:

  • 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.
  • 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.

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.

  1. Make a note of all of the categories that you wish to include in the calendar from your site.
  2. Make sure you have the names of the fields you want to include for each profile or category that you want on the calendar.

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.

↑ Contents

Style Example

<Field: Year><Field: TwoDigitMonth><Field: TwoDigitDay>^^^<Field: Subject>^<If: Field: Text>h**p://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>h**p://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.

↑ Contents

Create a Profile

  1. Create a profile in Coranto that will be used to generate the data file for smcCal. You can name it anything you want, but in the main profile settings you must:
    • Set the File Name to the name of the smcCal data file
    • Set the File Path to point to the directory that the smcCal data file is in
  2. These filter settings can be set to whatever values you wish.:
    • Filter By Time
    • Filter By Number
    • Skip Days
    • Skip Items
  3. Select the categories that you wish to see on the calendar.
  4. Select the news style that you created in the first step.
  5. Set the Display Coranto Link to whatever value you want.
  6. Set Enable Headlines to "No(Off)" unless you have a need for this profile to create the headlines file.
  7. smcCal will actually display the calendar so set HTML Template to "(none)".
  8. The Sort Order does not matter, smcCal since reads each line in the data file. I set mine to oldest first just because that seemed to make sense for a calendar.
  9. We created our anchors in the style, so you can set Anchors Tags off.
  10. Save your settings.

↑ Contents

Build News

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.

↑ Contents

Troubleshooting

Here are some things to look at if your setup isn't working:

  • Data File Format
    • Make sure the data separators are properly placed
    • Make sure that each item is on a new line
  • Path to the data file
  • Data file name

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.

Neat Calendar Tricks

Here are some more ideas for using Coranto and smcCal together.

↑ Contents

Multiple Calendars

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.

↑ Contents

Modifying index.cgi

NOTE: 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";
 }

↑ Contents

Making the Navigation Work

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.

↑ Contents

Using the Multi Calendar Hack

For 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:

h**p://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.

↑ Contents

Calendar Header & Footer

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.

↑ Contents

Change Calendar SSI Format

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.

  1. Copy the function and paste it just below the original function
  2. Change elsif ($style =~ /^days(\d+)$/) to elsif ($style =~ /^mystyle(\d+)$/)
  3. Find this code:

print "<tr>\n",
"<<td class=\"smc\">$date</td>\n",
"<td class=\"smc\">$title</td>\n",
"</tr>\n";

Edit to suit you. This will use a list:

print "<li>",
"$date - ",
"$title",
"</li>\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?

  • You can display a rolling list X number of days from today easily
  • You can use the same data for all information that you consider calendar type events.

↑ Contents

Styling With Coranto

These are ideas that I have not tested, but should work.

↑ Contents

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.

↑ Contents

More Suggestions

  • Choose the field to print on the calendar based on the category of news
  • Include more than one field as the event text on the calendar
  • Use the java popupmsg to display a teaser on mouseover
  • Display a message "No Details Available" if the text field is empty
  • Display the time of the event using the java popup

↑ Contents

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

Revision History

  • Original Published - August 11, 2003
    *August 17, 2003
    **Removed extra spaces in Coranto style example
    *August 18, 2003
    **Added alternate method to publish event dates
    *August 25, 2003
    **Added directions for using multiple calendars.
    **Added suggestion for writing year for recurring events.
    *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
    *November 13, 2003
    **Moved document location to Coranto Demo
    **Added links to Coranto Demo Homepage
  • July 28, 2006
    • Formatted for this Wiki and published here

↑ Contents

Final Notes

Original Document

Original Document written by Dale Ray on September 10, 2003.

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.

↑ Contents

Comments/Discussion

You can leave comments or discuss this article in this forum thread.

Categories:




Page last modified on February 02, 2009, at 07:24 PM