Google, iCal & XML Event List Calendar Documentation

Show your events in an elegant list format from your Google Calendar, an iCal feed or an XML file.

Item Support Product Site

Thank you for purchasing my item. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. Thanks so much!

Copy the Files

Installing this script is really easy. In your download folder is a folder called calendar. Copy that folder and its contents to your webserver. If you're planning on enabling caching, please also create a folder called cache in the same directory as you're copying the folder calendar to, as some servers may need this.


Included Files

This is a brief explanation of the purpose of each file. You can skip this if you want but I thought it was worth mentioning.

File Name Description
cache/ When caching is enabled, the cache files will be stored in this folder by default, so do not delete this folder.
images/ The folder where all the graphics for the calendar are located.
class/calendar.class.php This is the main calendar class where everything happens and where the HTML is generated.
class/ical.class.php A PHP class to parse iCal (.ics) data, written by Martin Thoma.
css/smoothness/jquery-ui-1.8.23.custom.css The jQuery UI CSS that is necessary for the date selector.
css/calendar(.min).css The CSS file where all the elements are styled. The different skins are included in this file and located at the bottom.
js/jquery-ui-1.8.23.custom.min.js The Jquery UI script that is necessary for the date selector.
js/calendar(.min).js The Javascript file where all the client-side code takes place. It requires jQuery to work.

Adding the JS & CSS

Before you can display the calendar you'll have to load the necessary Javascript and CSS files. Besides that you'll also need a copy of jQuery Add the following code your the <head> of your website.

Important! Keep in mind, that you may already have included jQuery and that you shouldn't include 2 copies. This is also applies to the jQuery UI JS & CSS.

<!-- jQuery UI Stylesheet (load only if needed) -->
<link rel="stylesheet" type="text/css" media="screen" href="calendar/css/smoothness/jquery-ui-1.8.23.custom.css" />

<!-- Main Stylesheet -->
<link rel="stylesheet" type="text/css" media="screen" href="calendar/css/calendar.min.css" />

<!-- jQuery (load only if needed) -->
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.2/jquery.min.js"></script>

<!-- jQuery UI (load only if needed) -->
<script type="text/javascript" src="calendar/js/jquery-ui-1.8.23.custom.min.js"></script>

<!-- Main Javascript -->
<script type="text/javascript" src="calendar/js/calendar.min.js"></script>

Displaying the Calendar

Displaying the calendar on your site is as easy as it gets. You can even display multiple calendars on the same site, each with different feeds. To display the calendar on your site, add the following PHP code.

Some options are actually required, so this current example will return an error. We'll cover options in the next chapter.

<?php

/* === Include the classes === */
require_once('calendar/class/calendar.class.php');
require_once('calendar/class/ical.class.php');

/* === Create a new Calendar object === */
$cal = new Calendar(array(
  /* options */
));

/* === Output the HTML === */
$cal->output();

?>

Options

Here's a complete list of all the options, their default values and what they're for. Options should be given as an array and the order doesn't matter. You cannot define the same option twice.

Name Type Default Description
url* array (empty) This is an array of the links to your XML files and/or iCal (.ics) feeds. All links & feeds will be merged together. It is a required option. Both external (http://) and internal files are allowed. In the next chapter you can read how to access your Google Calendar feed.
cache bool true Choose to enable or disable caching. When enabled, the script will cache the calendar events so it doesn't have to download them upon every request. Cache files will be stored in the cache folder. Empty the folder to clear the cache.
cache_dir string calendar/cache/ The path to the directory of the cache folder relative to your PHP file. The default configuration may not work if the path to the cache folder is different from the example.
cache_token int 1 If you place multiple calendars on your website with caching enabled, you must make sure they each have a different cache token so the appropriate cache files will be used.
cache_time int 86400 The number of seconds a cached file will be used. After this time the file with event data will be re-downloaded and cached. 1 hour = 3600 seconds.
excerpt_length int 50 Next to the event title is a shortened discription available. The excerpt_length is the maximum number of characters the description may be. This is to ensure that long descriptions won't break the calendar. Set to 0 to disable.
auto_title_width bool true When enabled, the event descriptions next to the titles will be aligned with eachother.
group_events_by_date bool false When enabled, events of the same day in the monthly and yearly view will be grouped together.
group_events_animate bool true If group_events_by_date is enabled, this option enables or disables the animation when a user clicks on a group.
scale string "month" This is the layout of the calendar. Choose between "day" (which will list events per day), "month" (which will list events per month) and "year" (which will list all the events of the whole year).
scale_change bool true If enabled, 3 links will pop up in the top-right corner of the calendar so the visitors can change the layout.
date_change bool true If enabled the visitor will be allowed to look at different dates of the calendar other than the default date.
date_picker bool true This option shows or hides a small button, which when clicked shows a calendar widget to make it easier for users to cycle through dates.
date_picker_keep_scale bool false When enabled, the scale (day, month, year) will be remembered when the date is changed using the date picker.
dst bool false When enabled, the calendar will take daylight saving time in account when calculating the start and end time. Keep this disabled when you're already taking daylight saving time in account when generating your iCal feed.
social_links bool true This will display a Facebook and Twitter button in each event description, which will both have a link to the event.
show_map_link bool true When enabled, a link will display next to the location, which opens Google Maps.
search_form bool true This will display a small search box above the calendar so users can search for events.
search_all_events bool true By default, only the events that are currently visible will be searched through, but if this option is enabled, it will search within all the events of the calendar.
time_format int 12 Choose the time format. Either 12 or 24.
extra_time int 0 If the event start and end times are off by a few hours, change this option. The extra_time is in seconds. 1 hour = 3600 seconds.
date_day_addition bool true Add 'st', 'nd', 'rd', 'th', etc after the dates. Turn off this feature when you're translating the month names into another language.
skin string "light" Choose between 1 of 3 skins. "light", "leaf" and "insect" are the available skins.
day int (today) The day of the month the calendar should initially show. By default it's the current day.
month int (today) The month of the year the calendar should initially show. By default it's the current month.
year int (today) The year the calendar should initially show. By default it's the current year.
* Required options

Examples

A few examples of configurations:


$cal = new Calendar(array(
  'url'        => array('http://example.com/events.xml'),
));
$cal = new Calendar(array(
  'url'        => array('events.xml', 'other_events.xml'),
  'extra_time' => 7200,
  'skin'       => 'leaf',
));
$cal = new Calendar(array(
  'url'          => array('http://example.com/feed.ics', 'events.xml'),
  'cache_dir'    => 'temp/',
  'day'          => 28,
  'month'        => 6,
  'year'         => 2012,
  'scale'        => 'day',
  'scale_change' => false,
  'date_change'  => false,
));

Translation

Translating the labels


You can easily translate all the labels of the calendar, including the month names. To do this, open class/calendar.class.php in a text editor. Next, change the labels from line 49 to 59 to whatever you like. You can also change the month names on line 59.

Step 1: Create a Google Account

If you haven't yet got a Google account, the first thing you'll have to do is create a Google account. Go to Google then click "Sign In" at the top right and then again "SIGN UP" at the top right. Next, follow all the steps and when you're done signing up, sign in with your new account.

Step 2: Create a new Calendar

After you've signed in, go the Google Calendar Homepage. Next create a new calendar by clicking the arrow next to "My Calendar" at the left. Fill in all the fields (calendar name, description, etc). You do not have to check "Make this calendar public" as you can use a private link, but you're free to check the checkbox. Click "Create Calendar" when you're done.

Step 3: Copy-paste the ICAL link

Now that you've created a new calendar, go to its settings by clicking the arrow under "My calendars" > (your calendar) > "Calendar Settings". In the calendar settings, scroll down to "Private Address" and click the "ICAL" button. In the popup window that appears copy the link (it'll look something like https://google.com/calendar/ical/0obr3o.../basic.ics) and use it as url parameter when adding a calendar to your site.

Remember Each time you click on "Reset Private URLs" within your calenar settings the link changes and you'll have to update the link.

Step 4: Adding Events

After you've linked your Google Calendar to this calendar, you can start adding events. When adding a new event, make sure you choose the correct calendar for your event. I highly recommend turning off the caching of the script while you add events so you'll see the changes show up immediately. Please note that due to some limitations, recurring events are not supported.


Example XML

Besides iCal (.ics) format, events can also be read from an XML file. Let's take a look at an example XML file.

The XML file can hold as many events as you want, this example has two.

<?xml version="1.0" encoding="iso-8859-1" ?>
<events>
  <event>
    <start_date>18/06/2012</start_date>
    <start_time>12:10</start_time>
    <end_date>19/06/2012</end_date>
    <end_time>16:45</end_time>
    <title><![DATA[Lorem Ipsum Event]]></title>
    <location><![DATA[Luxembourg City]]></location>
    <description><![CDATA[Lorem <strong>ipsum</strong> dolor]]></description>
  </event>
  <event>
    <start_date>18/06/2012</start_date>
    <start_time>11:30</start_time>
    <end_date>18/06/2012</end_date>
    <end_time>16:30</end_time>
    <title><![DATA[Lorem Ipsum Event]]></title>
    <location><![DATA[Melbourne, Australia/]]></location>
    <description><![CDATA[Lorem ipsum dolor]]></description>
  </event>
</events>

XML in Details

Here's a list of all the parts of an event in XML. The title, description and location must be put within <![CDATA[ ... ]]> tags so special characters and HTML is allowed.

Name Description
start_date* The start date of the event in the format dd/mm/yyyy.
start_time* The start time of the event in the format hh:mm. No am/pm please, the script will convert the time automatically if you've set the time format to 12.
end_date* The end date of the event in the format dd/mm/yyyy.
end_time* The end time of the event in the format hh:mm.
title The title of the event.
location The name of a city or place to add a location which will display in Google Maps.
description The description of the event
* Required tags

All-day Events

All-day events can be created by setting the start- and end time both to 0:00 and setting start- and end date one day after each other. Here's an example:

<event>
  <start_date>20/06/2012</start_date>
  <start_time>0:00</start_time>
  <end_date>21/06/2012</end_date>
  <end_time>0:00</end_time>
  <title><![DATA[Lorem Ipsum Event]]></title>
  <location><![DATA[Luxembourg City]]></location>
  <description><![CDATA[Lorem <strong>ipsum</strong> dolor]]></description>
</event>

Once again, thank you so much for purchasing this item. As I said at the beginning, I'd be glad to help you if you have any questions relating to this item. No guarantees, but I'll do my best to assist. If you have a more general question relating to the items on CodeCanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.