Prog how-to

Short description

Here is a fully customizable calendar control for your PHP applications. It is entirely written in php and can be easily adapted to your needs. Also it is free. The download links are displayed below:

Download

Download the component only here. This package contains only the classes afferent to the control.

I strongly recommend you download all the test classes (which include the Calendar classes as well), for a “live” use example. The full test package can be downloaded here. Here is the test link to see the control at work. One thing: prototype.js contained in the archive is the prototype framework used for Ajax and it is just a bundled reference, not an actual part of the project.

How it works

The calendar shows a full month. The header contains the current month and the year, plus two links to be used to switch to the previous / next month.

A date considered “selected” is rendered with a different CSS.

There is no formatting data in the calendar other than the generated CSS classes attached to various html tags. The programmer and the designer are the ones that will decide how to put together the needed CSS in order to make the control blend in the website.

Here is how the calendar looks like (it was taken from the test that can be found here).

There are links in the header on the left and right arrow shown and on each date. Each hyperlink triggers a Javascript function – there are default names for these functions. These names can be also changed

The control is not rendered in Javascript. Reasons: it requires a lot of javascript, plus if you need to display information other than just the days (and we need to display this additional information) then you need a roundtrip anyway.

Then what would be a good approach to change the calendar state (rendering):

• Wrap the calendar in another control let’s say<div class=’calendar’ id=’item1′>
• If the page is entirely rendered, just echo the component html where you want the calendar displayed
• If you want to change the calendar in place, then
  1. The Javascript functions triggered by the calendar shall send an Ajax request
  2. The callback function receives a json containing among other things the html associated with the calendar new state
  3. Replace the current calendar with the new one like that: document.getElementById(’item1′).innerHTML=retrieved_html
• Please try the test – it has all the Ajax stuff. It sounds tough, but actually it is extremely simple to implement!!!!

Features

Here is a list of features:

• Shows the current month, year
• Uses only CSS class names for rendering control. The programmer has to fully provide his own CSS definition that will make the calendar blend in his website
• There is a “selected date” that will be rendered using a different CSS class
• Besides the days in the calendar, you can show some additional data defined in a hash array before the rendering.
• The control has some links that trigger Javascript functions. The functions will be implemented by the programmer usually in order to whatever is needed on the server side according to the business requirements and prepare the calendar control for a new state.

Structure

The calendar is shipped in two PHP clases, a value object class with all the settings called CalendarData and the Calendar class with all the rendering, etc.

In a nutshell, here is how to use the control:

• Create an instance of CalendarData
• Fill out the needed attributes
• Create an instance of Calendar (passing the reference to the already created CalendarData object)
• Retrieve the control html using the accessor getHtml() from the calendar object

Depending where you are in your application, you can do the following:

• Echo the html in the appropriate place in order to have it rendered in the page
• If you are in the middle of an Ajax request processing, put the html in the object that will be converted later to json so that you will have the information in the request callback

Formatting

The control only generates classes attached to some of the table rows and all the table cells. It is programmer responsibility to tweak the css file in order to obtain the desired result. For example, the formatting obtained for our example that can be seen here, was obtained solely by appropriately adjusting the CSS file.

The classes generated by the control rendering functionality are the following:

• weekday – class attached to the td html tags that wrap around week days.
• weekend – class attached to the td html tags that wrap around week end days
• selected – class attached to the td html tag that corresponds to the selected day

If you need to have two calendars on the same page and render them differently, please wrap them in two div tags with different class names (div.calendar1 and div.calendar2) and provide the formatting info in your css file accordingly. Also, worth mentioning that the header lines are wrapped in a thead tag while the other ones are wrapped in a tbody. This will also help with organizing the formatting styles in the css file.

Some Images

Here are some images for the calendar control, in various configurations:
Without any values displayed

With both the values and the default values displayed

With the “width” style associated with the cells removed – so that will occupy minimum space and will look more like the calendars you saw already.

Some Code

Setting Calendar Data

function getData(){
	$dt = new CalendarData();

	// setup some information
	$dt->month = 3;
	$dt->year = 2009;
	$dt->values = array();

	$dt->selday = 12;
	$dt->selmonth = 3;
	$dt->selyear = 2009;

	$dt->values['2009-3-2'] = "4";
	$dt->values['2009-3-5'] = "2.5";
	$dt->values['2009-3-12'] = "1";

	$dt->showValues = true;
	$dt->showDefault = false;

	return $dt;
}

Rendering the Calendar

$dt = getData(); // get the calendar data

$showValues = getToggle($dt->showValues);
$showDefault = getToggle($dt->showDefault);

$cal = new Calendar($dt);

$html = $cal->getHtml();

And then somewhere in your html page:

<?php echo $html; ?>

This entry was posted on Saturday, May 9th, 2009 at 6:47 pm and is filed under php. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.