Home arrow Documentation arrow API Reference arrow Calendar Class
Home
FAQ
Documentation
Forums
License Key
Calendar Class Print

API Reference

Don't feel overwhelmed by the amount of options, the Calendar Publisher will set all of these for you. This is provided so that developers have a low level explanation.

Calendar Class
The calendar class is a wrapper around many functions in this application. The constructor syntax is:
<?
$cal = new calendar([ int year, [ int month, [ int day ] ] ]);
?>
Without any arguments, it defaults to checking $_REQUEST[] for "y", "m" and "d." If it can not find these, it will use the current date. E.g: 
$cal = new calendar();
Creates a calendar object with a date of today. However, if this is embedded in a php script and you go to http://yourserver.com/yourscript.php?m=12&d=21&y=2004 the calendar will be set to December 21st 2004.

Calendar Variables
Calendar variables are available directly after you create a calendar object. E.g.
<?php

   $cal = new calendar();
   echo($cal->month);

?>
 Will print November. Note that it is November at the the time of this writing.

When setting a calendar variable ALWAYS use the set() method.

int calendar
This is the internal ID of the calendar you wish to display. You should not need to change or set this as it is one of the options set by the Calendar Publisher.
<?php

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

?>
string theme
This is the string name of the theme the calendar should use. The default is taken from the default user's theme setting. See the themes/ directory in your Thyme installation for more options.
<?php

   $cal->set("theme", "sleek");

?>
boolean static
This tells the calendar that it may not enable links that change views and dates. The default is false. Links will also set the $_REQUEST variable "v" to:

"d" for day
"m" for month
"w" for week

From there, you must code in changing of views if you wish to do so. Most people will embed only one view of a calendar in their application and will not need to worry about this at all.
E.g.

<?php

   $cal->set("static", false);

?>
int row_height
This is the height for each row in a month or mini month view calendar. The default is 90 for a month and 0 for a mini month. E.g.
<?php

   $cal->set("row_height", 70);

?>
Will give you a slightly shorter calendar when viewing using display_month(). In views other than month and mini month, this has no effect. To control a calendar's width, put it inside a table and adjust that table's width.

boolean show_weeks
This shows the week numbers on the left hand side of a month view. The default is true. In other views, this has no effect. E.g.

<?php

   $cal->set("show_weeks", false);

?>
boolean show_events
This tells the calendar to show events. It defaults to true.
E.g.

<?php

   $cal->set("show_events", true);

?>
boolean event_links
This tells the calendar to make event names a click-able link. The default is true. E.g.
<?php

   $cal->set("event_links", false);

?>
string event_view_url
This is the url every event will go to when someone clicks on an event title and will be passed a query string containing eid and instance. eid is the ID of the event and instance is the date in YYYY-MM-DD format. These are noted by %eid and %inst. E.g.
<?php

   $cal->set("event_view_url", "/sales/view_sale.php?eid=%eid&date=%inst");

?>
may yield the url: http://mysite.com/sales/view_sale.php?eid=56&instance=2005-10-26

This can even be a JavaScript function. E.g.
<?php

   $cal->set("event_view_url", "javascript:MyFunction(%eid, %inst)");

?>
Provided, of course, MyFunction() exists in your JavaScript code.

Also see get_event().

boolean e_typename
This tells the calendar to display each event's type in brackets. For instance an event named "Christmas" set to type "Holiday" may be displayed as "Christmas [Holiday]". The default is false. E.g.
<?php

   $cal->set("e_typename", true);

?>
boolean e_popup
Display events in a new window. The default is false. E.g.
<?php

   $cal->set("e_popup", true);

?>
float timezone
This sets the timezone offset from GMT. For instnace, Eastern Standard Time would be set to -5.0.
<?php

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

?>
int dst
This is the internal Daylight Saving Time configuration of the calendar. This should only ever be set by the Calendar Publisher.

string header
This is the header text at the top of a calendar. The default depends on what you are viewing. E.g.
<?php

   $cal->set("header", "Events in %month");

?>
This replaces the following strings with the following values:
  • %weekday - weekday name (Sunday - Saturday)
  • %month - name of month (January - December)
  • %mday - day of the month (1 - 31)
  • %mon - numeric representation of month (1 - 12)
  • %year - numeric representation of year ( 0 - 9999)

string header_align
This aligns the calendar's header text. The default is "m" for middle. Other values are "l" (lower case L) for left or "r" for right. E.g.
<?php

   $cal->set("header_align", "r");

?>
boolean show_header
This tells the calendar whether or not to display the a header. The default is true. E.g.
<?php

   $cal->set("show_header", false);

?>
boolean show_header_links
This tells the calendar whether or not to display Next/Previous links in the header. These are represented by images. The default is true. E.g.
<?php

   $cal->set("show_header_links", false);

?>
string txt_next
This is the text used for the 'Next' link calendar header. It will default to the theme's 'Next' image. E.g.
<?php

   $cal->set("txt_next", ">>");

?>
string txt_prev
This is the text used for the 'Previous' link calendar header. It will default to the theme's 'Previous' image. E.g.
<?php

   $cal->set("txt_prev", "<<");

?>
string img_next
This is the url of the image of the 'Next' button in a calendar header. It will default to the theme's 'Next' image. E.g.
<?php

   $cal->set("img_next", "/images/next_button.gif");

?>
string img_prev
This is the url of the image of the 'Previous' button in a calendar header. It will default to the theme's 'Prev' image. E.g.
<?php

   $cal->set("img_prev", "/images/prev_button.gif");

?>
int time_interval
This only effects a day view calendar. It tells the calendar that how an hour should be divided and has 3 possible values:
  • 1 - divide hours by 1. This will give you 1 table row per each hour in the day view
  • 2 - divide hours by 2. This will give you 2 table rows for each hour, or 1 row for every 30 minutes.
  • 4 - divide hours by 4. This will give you 4 table rows for each our, or 1 table row for every 15 minutes.
E.g.
<?php

   $cal->set("time_interval", 4);

?>
int work_start_hr
This is the hour, in 24 hr format, that the day starts on in a day view. E.g.
<?php

   $cal->set("work_start_hr", 9);

?>
Will make the "work day" start at 9 am.

int work_end_hr
This is the hour, in 24 hr format, that the day ends on in a day view. E.g.
<?php

   $cal->set("work_end_hr", 18);

?>
Will make the "work day" end at 6 pm.

boolean hil_day
This tells the calendar to highlight the selected day in any calendar it displays. The default is true. E.g.
<?php

   $cal->set("hil_day", false);

?>
boolean hil_week
This tells the calendar to highlight the selected week in display_month() and display_month_mini(). The default is false. E.g.
<?php

   $cal->set("hil_week", true);

?>
int width
This is the width you wish the calendar to be. The default is 100%. E.g.
<?php

   $cal->set("width", 600);

?>
int week_start
The day of the week that the calendar should start on. 0 = Sunday - 6 = Saturday. E.g.
<?php

   $cal = new calendar();

   // start on Monday
   $cal->set("week_start", 1);

?>
int hour_format
This is the hour format when displaying times. This should either be set to 12 or 24. A 12 hour format includes am/pm where as a 24 hour format is simply the hour or "military time."

int abbr_weekdays
This tells the calendar how many characters to abbreviate weekday names to. The default depends on the calendar view. 0 means do not abbreviate weekday names. E.g.
<?php

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

?>
boolean exclude_outside
For a month view, this tells the calendar not to display days that are outside of the current month. The default is false.
<?php

   $cal->set("exclude_outside", true);

?>
int e_size
In a month view, this tells the calendar how large or small the events should be. Valid values are:
  • 0 - normal
  • 1 - smaller
  • 2 - smallest

The default is 0. E.g.
<?php

   $cal->set("e_size", 2);

?>
boolean e_collapse
In a month view, this tells the calendar to collapse long event titles. Full titles will be displayed when the user's mouse hovers over the event. The default is false.
<?php

   $cal->set("e_collapse", true);

?>
string minical_date_url
The link that clicking on a day in a mini month calendar will point to. This replaces the following strings:
%d = the day number
%m = the month number
%y = the year number

E.g. http://www.myserver.com/page.php?day=%d&month=%m&year=%y may yield http://www.myserver.com/page.php?day=23&month=11&year=2004 or you may even use a JavaScript function like javascript:myFunction(%y,%m,%d). E.g.
<?php

   $cal->set("minical_date_url", "view_sales.php?day=%d&month=%m&year=%y");

?>
The default is a link to the current page that sets:
m = %m
d = %d
y = %y
E.g. index.php?d=23&m=11&y=2004

int mday
The number of the day of the month of the calendar. E.g. if the calendar date is set to 2004-11-24, $cal->mday will have a value of 24.

int wday
The number of the day of the week of the calendar where 0 = Sunday and 6 = Saturday. E.g. if the date of the calendar is set to a Tuesday, $cal->wday would have a value of 2.

int mon
The month number of the calendar where 1 = January and 12 = December. E.g. if the calendar is set to November 2nd 2004, $cal->mon would have a value of 11.

int year
The 4 digit representation of the year of the calendar. E.g. 2004, 1993, etc..

string weekday
This is the weekday name of the calendar. E.g. if the date of the calendar is 2004-11-2, $cal->weekday would have a value of Tuesday.

string month
This is the name of the month of the calendar. E.g. if the date of the calendar is 2004-11-2, $cal->month would have a value of November.

int time
The internal timestamp of the calendar date. All date calculations are based on this variable. You may change it to alter the date that the calendar displays.
<?php

   $cal = new calendar();

   echo("the calendar date is ");
   echo($cal->format_date("l n/j/Y"));
   echo("<br>\n");

   # display today
   $cal->display_day();

   # remember 86400 seconds = 1 day
   $cal->set("time", $cal->time + 86400);

   echo("the calendar date is ");
   echo($cal->format_date("l n/j/Y"));
   echo("<br>\n");

   # display tomorrow
   $cal->display_day();

?>
See also: get_event_list(), format_date(), display_day()

int w_starttime
The unix timestamp of the first day of this week. This is set when the calendar object is created and if/when the time variable is changed. This should never be altered directly. It is calculated based on the value of week_start. E.g.
<?php

   $cal = new calendar();

   echo("this week starts on ");
   echo($cal->format_date("l n/j/Y", $cal->w_starttime));
   echo("<br>\n");

?>
See also: format_date()
int m_starttime
The unix timestamp of the first day that a month display should start on. This is set when the calendar object is created and if/when the time variable is changed. This should never be altered directly. It is calculated based on the value of week_start. E.g.
<?php

   // today is 2004-11-4
   $cal = new calendar(2004, 11, 4);

   // note in 2004, 11-1 was a Monday

   // weeks start on sunday
   $cal->set("week_start", 0);


   echo("this month will start on ");
   echo($cal->format_date("l n/j/Y", $cal->m_starttime));
   echo("<br>\n");

?>
This will print "this month will start on Sunday 10/31/2004." Because 10/31 is the first Sunday on or before 11/1.

See also: week_start, format_date().

Calendar Methods
Methods are accessed after the calendar object is created. E.g.
<?php

   $cal = new calendar();
   $cal->display_month();

?>
void set ( string variable, mixed value )
This method sets a calendar variable. E.g.
<?php

   $cal->set("show_header", true);

?>

string format_date ( string format [, int timestamp] )

string format is exactly like PHP's date's format string. These are some common options:
format character Description Example returned values
a Lowercase Ante meridiem and Post meridiem am or pm
A Uppercase Ante meridiem and Post meridiem AM or PM
d Day of the month, 2 digits with leading zeros 01 to 31
D A textual representation of a day, three letters Mon through Sun
F A full textual representation of a month, such as January or March January through December
g 12-hour format of an hour without leading zeros 1 through 12
G 24-hour format of an hour without leading zeros 0 through 23
h 12-hour format of an hour with leading zeros 01 through 12
H 24-hour format of an hour with leading zeros 00 through 23
i Minutes with leading zeros 00 to 59
j Day of the month without leading zeros 1 to 31
l
(lowercase 'L')		 A full textual representation of the day of the week Sunday through Saturday
m Numeric representation of a month, with leading zeros 01 through 12
M A short textual representation of a month, three letters Jan through Dec
n Numeric representation of a month, without leading zeros 1 through 12
S English ordinal suffix for the day of the month, 2 characters st, nd, rd or th. Works well with j
t Number of days in the given month 28 through 31
w Numeric representation of the day of the week 0 (for Sunday) through 6 (for Saturday)
W ISO-8601 week number of year, weeks starting on Monday (added in PHP 4.1.0) Example: 42 (the 42nd week in the year)
Y A full numeric representation of a year, 4 digits Examples: 1999 or 2003
y A two digit representation of a year Examples: 99 or 03
z The day of the year (starting from 0) 0 through 365
For more options see the documentation for date() at http://www.php.net/manual/en/function.date.php

If no timestamp is given, it uses the calendar's time. E.g.
<?php

   $cal = new calendar(2004,12,4);
   echo($cal->format_date("l F j, Y"));

?> Would print Saturday December 4, 2004

void apply_style ( [ string theme ] )
This will include all the style sheets that you may need to correctly display the calendar. Per w3c standards this should go between the <head> tags. If you wish to ALSO include the CSS from a theme, pass the theme's name as an argument. E.g.
<?php

   $cal->apply_style("sleek");

?>
If you are using your own CSS from the Style Editor, you should not include a theme's CSS and therefore not pass apply_style any arguments.

void display_day ( void )
Displays a calendar's day view. E.g.
<?php

   $cal->display_day();

?>
void display_week ( void )
Displays a calendar's week view. E.g.
<?php

   $cal->display_week();

?>
void display_month ( void )
Displays a calendar's month view. E.g.
<?php

   $cal->display_month();

?>
void display_month_mini ( void )
Displays a calendar's month view as a mini calendar. E.g.
<?php

   $cal->display_month_mini();

?>
array get_event_list ( string view [, mixed date ] )
This returns an array of days that contain arrays of event ids. The number of days and the day it starts on depends on the view. Possible view options are:

  • "day"

    • The array may contain 1 element. The element will be an array of event ids for events that occur that day.

  • "week"

    • The array may contain 7 elements. Each containing an array of event ids that happen on that day in the iteration. The first day (array index 0) will start on
    $cal->w_starttime.

  • "month"

    • The array will contain a variable amount of elements depending on which day the month starts and ends on. The first day (array index 0) will start on
    $cal->m_starttime.

The optional date argument will start the event list on a different date. The default for this is the calendar's date. The argument can be a timestamp (e.g. $cal->time) or a string that has the same format as those accepted by gmtstrtotime. No matter what you set this to, the event list will always start on the correct day as dictated by w_starttime or m_starttime. E.g.


<?php

   $elist1 = $cal->get_event_list("month", "2003-11-02");
   $elist2 = $cal->get_event_list("month", "2003-11-23");

?>
In the above example, $elist1 and $elist2 will be identical.

Each element of the event list may contain an array of events. Each event is an array of information pertaining to that event. Assuming we're getting an event list for a week:
<?php

// create calendar object
$cal = new calendar();

// get this week's events
$week = get_event_list("week");


// print our week array
print_r($week);

?>

Example output may look like:

Array
(
    [0] => Array
        (
        )

    [1] => Array
        (
            [0] => Array
                (
                    [id] => 7560
                    [start] => 1121198400
                    [end] => 0
                    [freq] => 0
                    [finterval] => 0
                    [byday] =>
                    [bymonthday] =>
                    [bymonth] =>
                    [bysetpos] =>
                    [wkst] =>
                    [allday] => 0
                    [timezone] => -5
                    [dst] => 13
                    [override_id] => 0
                    [title] => Joe Pass in concert
                    [use_tz] => 0
                    [icon] => event_icons/concerts/JoePass.jpg
                    [duration] => 01:00:00
                    [flag] => 0
                    [type] => 0
                    [calendar] => 32
                    [type_name] =>
                    [type_icon] =>
                    [type_style] =>
                    [end_timestamp] => 0
                    [endtime] => 0
                    [starttime] => 1121198400
                    [next] => 1121198400
                    [instance] => 1121198400
                )

        )

    [2] => Array
        (
        )

    [3] => Array
        (
            [0] => Array
                (
                    [id] => 7559
                    [start] => 1121371200
                    [end] =>
                    [freq] => 3
                    [finterval] => 1
                    [byday] =>
                    [bymonthday] =>
                    [bymonth] =>
                    [bysetpos] =>
                    [wkst] => 1
                    [allday] => 0
                    [timezone] => -5
                    [dst] => 13
                    [override_id] => 0
                    [title] => Amateur Comedy Night
                    [use_tz] => 0
                    [icon] =>
                    [duration] => 01:00:00
                    [flag] => 0
                    [type] => 0
                    [calendar] => 32
                    [type_name] =>
                    [type_icon] =>
                    [type_style] =>
                    [end_timestamp] =>
                    [endtime] =>
                    [starttime] => 1120161600
                    [start_timestamp] => 1120161600
                    [next] => 1121371200
                    [instance] => 1121371200
                )

        )

    [4] => Array
        (
        )

    [5] => Array
        (
            [0] => Array
                (
                    [id] => 7562
                    [start] => 1121522400
                    [end] => 2005-7-31
                    [freq] => 3
                    [finterval] => 1
                    [byday] =>
                    [bymonthday] =>
                    [bymonth] =>
                    [bysetpos] =>
                    [wkst] => 1
                    [allday] => 0
                    [timezone] => -5
                    [dst] => 13
                    [override_id] => 0
                    [title] => Barney on Ice
                    [use_tz] => 0
                    [icon] => event_icons/concerts/port_char_barney.jpg
                    [duration] => 01:00:00
                    [flag] => 0
                    [type] => 0
                    [calendar] => 32
                    [type_name] =>
                    [type_icon] =>
                    [type_style] =>
                    [end_timestamp] => 1122831323
                    [endtime] => 1122831323
                    [starttime] => 1120312800
                    [start_timestamp] => 1120312800
                    [next] => 1121522400
                    [instance] => 1121522400
                )

            [1] => Array
                (
                    [id] => 7561
                    [start] => 1121540400
                    [end] => 0
                    [freq] => 0
                    [finterval] => 0
                    [byday] =>
                    [bymonthday] =>
                    [bymonth] =>
                    [bysetpos] =>
                    [wkst] =>
                    [allday] => 0
                    [timezone] => -5
                    [dst] => 13
                    [override_id] => 0
                    [title] => John Coletrane
                    [use_tz] => 0
                    [icon] =>
                    [duration] => 01:00:00
                    [flag] => 0
                    [type] => 0
                    [calendar] => 32
                    [type_name] =>
                    [type_icon] =>
                    [type_style] =>
                    [end_timestamp] => 0
                    [endtime] => 0
                    [starttime] => 1121540400
                    [next] => 1121540400
                    [instance] => 1121540400
                )

        )

    [6] => Array
        (
        )

)
You can see it is a 7 element array (0-6), each element representing 1 day of the week. Each day of that week may have events. These are stored as an array of event information. This event information may or may not contain the information you require. For instance, it will contain the title of the event, but not the notes. Usually, you'll need more than this. To retrieve all the properties of an event, you must use the get_event() method to return an event object. E.g.
<?php

   // fill the event list

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

   // iterate through the 7 days

   for($i = 0; $i < 7; $i++)
   {
    
      // if we do not have any events,
      // skip to the next day

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


      //  print a header for today

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


      // step through each event for
      // this day

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

        $e = $cal->get_event($event['id'], $event['instance']);
        echo($e->title . ": ". $e->notes ."<br>\n");

      }

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

   }

?>
For more information, see the tutorial on embedding calendars.

event object get_event ( int event id, date instance )
This method returns an event object, and takes an event id and instance as it's argument. E.g.
<?php

   $e = $cal->get_event(32, "2007-1-23");

   echo($e->title);

?>
The id of the event is the internal identifier and the instance is used to calculdate timezone and DST information. Both of these would be obtained from get_event_list().