Thyme - A PHP Calendar - Advanced Integration Tutorial

Home

Documentation

Advanced Integration

Advanced Integration Tutorial

Advanced Integration Tutorial

We are going to be using extrovert/tutorials/examples/browning?y=2005&m=7&d=11 as an example site. Note that it's function over fashion for this example. Also note that the query string sets the date to 7/11/2005. The events we will be looking at and the examples referenced here will be for that week.

If you have not done so already, please read the tutorial on Embedding a Calendar

We will cover the 5 main calendar aspects of this site:

Initial Setup
Creating the Calendar Object (using the Calendar Publisher)
Mini Calendar
The Selected Week's events (left)
This Week's events (under the mini calendar)

Initial Setup

For the initial setup, create a calendar called "Browning Concert Hall." We'll place 4 events in this calendar:

Amateur Comedy Night - repeats every Thursday
Joe Pass in concert - Tuesday 8pm
John Coletrane - Saturday 7pm
Barney on Ice - Repeats weekly on Saturday, ends July 31st

The last occurrence of Barney on Ice happens on July 30th. We'll edit that single instance of that event and change the notes to let visitors know that it's their last chance to catch that show.

Creating the Calendar Object

As of now, we have a template of where each element is going to go. See extrovert/tutorials/examples/browning/index_step1.php . We'll cover and explain each part of the Calendar Publisher options we had to set:

General

Calendar - Browning Concert Hall
View - Mini Month. We want to create a calendar that displays a miniature month.
Date - check the box Set to Current Date. We want the calendar to default to using the current date.
Week Starts On - Monday. We want our weeks to start on Monday
Hour Format - Not important, In no part of this will the calendar itself be displaying time.
Static - Unchecked. We want the days to be clickable so that we can use the values.
Hightlight Day - Unchecked. We will be navigating through weeks, not days. So we want to check the next option.
Hightlight Week - Checked. We want the calendar to highlight the selected week so that we know exactly which days we are looking at.

Style Editor

Use Theme - default. The default theme makes no changes to html code and is the best option since we are going to use the Style Editor.
Apply Style From - Style Editor. We want to use the Style Editor to alter the look of the calendar so that it matches the look of our site.
This is self-expanitory and is used to change the look of the calendar to match the look of our site.

Events

Show Events - Checked. We want to show events. In a mini calendar, that means days with events are shown in bold.
Event Links - Not Important. In the mini calendar, days with events are shown in bold, but actual events themselves are not shown.
Event Link Url - Not Important. Same reason as above.

Locale

Set to proper timezone and DST.

Header

Show Header - Checked. We want to display the calendar's header.
Align Header Text - Center. We want the header text to be centered.
Header Text - Leave Blank. The default header text is fine.
Show Header Links - Checked. We want Next/Previous buttons in our header
Next Image Url - /browning/images/next_sm.gif. This is our custom next button. None of the themes' buttons fit our color scheme.
Previous Image Url - /browning/images/prev_sm.gif. See explanation above.

Day View

Not important. Our calendar displays the month.

Month Views

Show Weeks - Not important. A mini calendar will never show week numbers.
Row Height - Leave Blank. The default height is fine for us.
Limit Weekday Names To - 3 chars. We only want are weekday names to be 3 chars long.
Mini Month Date Link - Leave Blank. The default will be a link to the current page with d,m, and y set to the calendar's day, month, and year respectively. This is fine for our purpose.

Excluding CSS, this generated the following code:



<?php

############################################################

# base path of files, with trailing slash
define("_CAL_BASE_PATH_", "/usr/local/apache/htdocs/thyme/");

# base url for calendar, with trailing slash
define("_CAL_BASE_URL_", "http://192.168.1.111:80/thyme/");

include_once(_CAL_BASE_PATH_ . "include/classes/class.calendar.php");

############################################################


$cal = new calendar();

# general
#############


$cal->set("calendar", 32);


$cal->set("week_start", 1);


$cal->set("hour_format", 12);
$cal->set("editable", 0);
$cal->set("static", 0);
$cal->set("hil_day", 0);
$cal->set("hil_week", 1);
$cal->set("theme", "default");

# events
####################
$cal->set("show_events", 1);



# locale
####################

$cal->set("timezone", -5.0);


$cal->set("dst", 13);




# header
##############
$cal->set("show_header", 1);
$cal->set("show_header_links", 1);
$cal->set("header_align", "m");
$cal->set("img_next", "/browning/images/next_sm.gif");
$cal->set("img_prev", "/browning/images/prev_sm.gif");

# day view
###############

# month view
###############
$cal->set("abbr_weekdays", 3);

$cal->display_month_mini();

?>

Now we're going to paste that code into our PHP file for Browning Concert Hall.

Note that the last line actually displays the calendar. We will cut and paste this line in the exact spot we want the mini calendar to be printed as outlined in the Mini Calendar section.

We now have a calendar object that is ready for use in our next few sections.

Mini Calendar

We can now take our code that prints the mini calendar

$cal->display_month_mini();

... and paste it into our Mini Calendar section noted in extrovert/tutorials/examples/browning/index_step1.php as Mini Calendar Here. The result looks like this: extrovert/tutorials/examples/browning/index_step2.php?y=2005&m=7&d=11 .

Notice you can click on a day in the Mini Calendar and it will highlight the selected week for you. Each link sets the query string variables d, m, and y to the corrosponding day, month, and year respectively. The calendar will read these and adjust it's time accordingly.

The Selected Week's Events

First we want to print the header links so that we can navigate through weeks. The calendar holds the month, day, and year in the variables mon, mday, and year. We know that the calendar will take these from the query string variables m, d, and y respectively. So, to generate our links, we can simply do:

$link_prev = '<a href="?y='. $cal->year .'&m='. $cal->mon .'&d='.
              ($cal->mday - 7) .'"><<</a>';

$link_next = '<a href="?y='. $cal->year .'&m='.  $cal->mon .'&d='.
              ($cal->mday + 7) .'">>></a>';

Note that this just subtracts or adds 7 to mday. What if this generates a negative number, or a number that goes beyond this months days like 11/-3/2005 or 11/34/2005? Thyme will automatically compensate for this. It knows that 11/34/2005 is really 12/4/2005.

Next we need to print our date heading. I.e. mm/dd/yyyy - mm/dd/yyyy. In order to do this, we need to know what day this week starts on. This can vary based on the setting of week_start. Thyme holds the time of the start of the week in the variable w_starttime. So let's set our heading based on this.

# today
$heading = $cal->format_date("n/j/y - ", $cal->w_starttime);

# last day of the week, note 86400 seconds = 1 day
$heading .= $cal->format_date("n/j/y", $cal->w_starttime + (86400 * 6));

Now that we have all the variables for our heading set. Let's print the whole thing out:


echo($link_prev . "         ");
echo($heading);
echo("         " . $link_next);

This should print:

<< 7/11/2005 - 7/17/2005 >>

Now we'll need a list of events that happen on whatever date the calendar is set to. We can do this using get_event_list. Since it defaults to using the calendar's current date, we only need to pass it the view argument. In our case, we wish to display a list of events that happen for the week so our view will be "week."

$days = $cal->get_event_list("week");

Now $days is an array representing the 7 days in a week starting at index 0. I.e. the first day of the week is $days[0]. Each element is an array of events that occur on that day. If a day has no events, the array will be empty. A print_r of $days would look like this:

print_r recursively prints an array or object. For more information see the documentation on the PHP website.

As you can see, each day contains an array of events and each event itself is an array of values. These might seem a lot to swallow at first. The only ones we are concerned with are id and instance. The id is the internal identification number of this event, and instance is the instance date that this event occurs on. The instance is needed to calculate timezone offsets between the event itself and the calendar's timezone (or locale) settings.

Now we need to step through each day, then through each event, printing some information about the event. To step through each day, knowing that we have 7 days, we'll use a simple for loop. Then, to step through each event, we can use a foreach loop. An example would look like this:

for($i = 0; $i < 7; $i++)
{

   foreach($days[$i] as $event)
   {

      echo("event with id ". $event['id'] ." happens on day ". $i ."<br>");

   }


}

The above should print:

event with id 7560 happens on day 1
event with id 7559 happens on day 3
event with id 7562 happens on day 5
event with id 7561 happens on day 5

Great! .. but not very informative. Let's create an event object to get more information about this event using the calendar method get_event. A simple example would look like this:

for($i = 0; $i < 7; $i++)
{

   foreach($days[$i] as $event)
   {

      $e = $cal->get_event($event['id'], $event['instance']);
      echo($e->title ." happens on day ". $i ."<br>")
;

   }


}

The above example would print:

Joe Pass in concert happens on day 1
Amateur Comedy Night happens on day 3
Barney on Ice happens on day 5
John Coletrane happens on day 5

Now we're getting closer to something that resembles information. Instead of day 1, day 3, etc.. let's print some date information.

for($i = 0; $i < 7; $i++)
{

   # remember 86400 seconds = 1 day

   echo("<b>Events for ");
   echo($cal->format_date("l n/j/Y", $cal->w_starttime + ($i * 86400)));
   echo("</b> : <br>");

   foreach($days[$i] as $event)
   {

      $e = $cal->get_event($event['id'],$event['instance']);
      echo($e->title);
      echo(" starts at ". $cal->format_date("g:i a", $e->start) ." <br>");

   }

}

This will print:

Events for Monday 7/11/2005 :
Events for Tuesday 7/12/2005 :
Joe Pass starts at 8:00 pm
Events for Wednesday 7/13/2005 :
Events for Thursday 7/14/2005 :
Amateur Comedy Night starts at 7:00 pm
Events for Friday 7/15/2005 :
Events for Saturday 7/16/2005 :
Barney on Ice starts at 11:00 am
John Coltrane starts at 5:00 pm
Events for Sunday 7/17/2005 :

Using the notes and icon object variables along with some tables, I created what you can see at extrovert/tutorials/examples/browning?y=2005&m=7&d=11 . For the pictures, I added them under icons/ and used the event icon variable. For more information on adding icons, see the FAQ.

This Week's Events

For the "This Week" link that brings the calendar to the current week, something as simple as this will do:

   <a href='<?php echo($_SERVER['PHP_SELF']) ?>'><b>This Week</b></a>

Passing the calendar no date information will default it to the current date.

Now we must create a list of events that happen THIS week regardless of what week the calendar is on. We'll get the list using the method get_event_list. We also need to pass it a date. Today in fact.

An alternative would be to reset the calendar's internal time using $cal->set("time", ... ). However, if this were being printed before the mini calendar or the Selected Week's Events, they would both always point to the same date no matter what date someone has clicked on because we would have manually set the calendar's date. For this reason, it is good practice to pass a date or timestamp to get_event_list when you want a list of events for a date other than what the calendar is set to. If this is gibberish to you, just remember to always pass get_event_list() _ex_localtime() when you want a list for right now.

We need the timestamp for today based on the timezone and DST setting of the calendar. For this we use the global function in Thyme called _ex_localtime().

$days = $cal->get_event_list("week", _ex_localtime());

Now we have an array called days. We know this array will have up to 7 elements since a week has 7 days. Each element in the array will be an array of event ids that happen on those days. Assuming you've covered the Selected Week's Events section of the tutorial, the following should make perfect sense.


// get our event list

$days = $cal->get_event_list("week", _ex_localtime());

// step through 7 days

for($i = 0; $i < 7; $i++)
{

   // skip to the next day if we have no events

   if(!count($days[$i])) continue;

   // heading for today will just be the
   // weekday name

   echo("<b>");
   echo($_cal_weekdays[($cal->week_start + $i) % 7]);
   echo("</b><br>");


   // step through each event for this day

   foreach($days[$i] as $event)
   {
      // get our event object
      $e = $cal->get_event($event['id'],$event['instance']);

      // print the name of the event
      echo("<b>". $e->title ."</b><br>");

      // print the start time of the event
      echo($cal->format_date("g:i a", $e->start));

      echo("<br><br>");

   }

}

The only major difference is the heading. We are using the global array $_cal_weekdays to obtain the weekday names. Since we know the calendar week will start on the day indexed by week_start, we can use this to determine what week day we are on. We are on week_start + $i. At the first iteration, $i is 0, and we are on the first day of our week which starts on week_start.

Since $_cal_weekdays only has 7 items (0 - 6 or Sunday - Saturday), we also need to make sure we don't go over 6. An easy way to do this is to use % (modulus) 7. This gives us the remainder of the value divided by 7. If the value is less than 7, it simply returns that value. This will always give us the correct index to use in $_cal_weekdays. A longer equivilent of this would be something like:

   // heading for today will just be the
   // weekday name

   echo("<b>");

   $wday = $cal->week_start + $i;
   if($wday == 7) $wday = 0;

   echo($_cal_weekdays[$wday]);

   echo("</b><br>");

Using some HTML tables that I've wrapped around printing of the event list, I've created what you can see at
extrovert/tutorials/examples/browning?y=2005&m=7&d=11

Note that if you navigate to the week that contains July 30th, you'll see that the notes for that instance of "Barney on Ice" lets visitors know it is the last chance for them to see that show.

From what you've learned in this tutorial, you should be able to, at the very least, duplicate the example site's functionality.

View entire source:

index.php

View example site:

extrovert/tutorials/examples/browning?y=2005&m=7&d=11