lucid calendar
Introduction
 

This is the lucid calendar application. It is calendaring software written with the PHP programming language interfacing with a MySQL database. This application is free software. You should have received a copy of the GPL along with it.

The primary goals of this software are as follows.

  • Calendar software which allows a small group of posters to display information on a website.
  • Simple methods which allow webmasters to draw the calendars.
  • A high degree of customizability for the appearance of the calendars.
  • Easy-to-use, web-based administration tools for the posting, modification, and deletion of events.

Please note that I mention that the idea behind the lucid calendar is that there will be a small number of people with the ability to post information, which may then be viewed by a much larger number of people. This is in contrast to a great deal of the calendaring software available, which is often targeted toward an office environment where there are roughly as many posters as viewers. Instead this is targeted towards web site owners who wish to display certain news or events on their website for the general public to see. I wrote this in direct response to requests for such a thing by several of the clients of Lucid Designs which is my web development company.
 
This is version 0.22 of the software. It is stable and useful in its current state. The value of the release version merely indicates that there are many new features that I wish to implement in the future.

The documents you will probably want to read are:

  
Requirements
 

This application requires that you have the PHP scripting language running on your webserver. For development, I'm using PHP 4.0.1pl2. It has been tested as far back as PHP 3.0.12, but I suspect that earlier versions of PHP3 would work fine without modifications. The program also requires that you have MySQL installed and running, and that you have permission to set up new tables for yourself on it. I suspect that the common system for deployment will be Apache/mod_php3/MySQL on a *NIX system. I use Linux for all of my development, but there's nothing that should make it function differenly on any other UNIX that I'm aware of.
 
I have tried to make lucid calendar as easy to use as I can, but I do assume that the user has some farmiliarity with PHP. Nothing crazy, the basics should do fine. To learn more, look here. Also, a fairly step-by-step set of setup instructions can be had by reading the INSTALL file.

  
Implementation
 

Drawing a calendar is designed to be a simple process. On the page where you want to draw the calendar, include the following code at the top of the page.
 

     <?php
     require("./cal.api");
     $mymonth = new month();
     ?>

 
In the <head> section of the page, include the php code
 
     <?php js_popup(); ?>

 
which will generate some needed javascript.
 
Then, at the point in the page where you want the calendar to appear, use the code
 
     <?php
     $mymonth->draw();
     ?>

 

This is the most basic implementation of the calendar drawing feature. It will draw the current month's calendar using the default colors, sizes, spacings, etc. In practice you will probably want to do three additional things, The first is to enclose the calendar within a simple table which will constrain its extent on the screen. You do not have to do this, but the display HTML generated was designed with this in mind. The second thing is that you will often wish to specify the month and year to draw when you declare your month object. The third thing is that you may wish to alter the default display properties for the calendar display in the draw method. The entire code for such an instance might look like this.


 
     <?php
     require("cal.api");
     $mymonth = new month("01","2000");
     ?>

     .
     . /* beginning of html */
     .

     <head>
     <title>calendar page</title>
     <?php js_popup(); ?>
     </head>

     .
     . /* somewhere in the page body */
     .
     
     <table width="85%" cellpadding="0" cellspacing="0" border="0">
     <tr>
       <td bgcolor="#000066">

     <?php
     $mymonth->draw(array("cellspacing" => "2" , "cellpadding" => "2" ,
                           "top_row_align" => "center" , "table_height" => "300px" ,
                           "top_row_cell_height" => 20 , "bgcolor" => "#cccccc" ,
                           "row_align" => "left" , "row_valign" => "top" ,
                           "font_size" => "-1") );
     ?>
       </td>
     </tr>
     </table>

As you can see, it is very easy to specify the particular month which you wish to display (January, 2000 in this case). It is a requirement that you use the full four digits to indicate the year to be used.

The most complicated method is the one used to draw the month in question. It takes an array as its argument which may be used to specify many of the display parameters. It is documented fully in the api section.

There are several other methods available in the month object. These are also documented documented in the api section.
 
Any events which have been posted to the events database for the month you draw will show up on the calendar display. When you click on an event, a popup window will appear with the full text for that particular event. This popup window will open the page "showevent.php3" which may be modified to suit the design of your particular site. An example "showevent.php3" is included in the source distribution. It uses the get_event_info() function to retrieve information from the database. This function is also documented in the api section.