Events Calendar Developer's Guide

Table of Contents

• Installation Process of the PHP Version
  • Requirements
  • Unzip Files to Your Web Folder
  • Access Database Libraries
  • Migration to a Different Database
  • Create a Database on Your Database Server
  • Setup Configuration File
  • Set Scheduled Tasks
  • Include Zapatec Suite
• Installation Process of the Java Version
  • Requirements
  • Install from WAR
    • Create the db Schema
    • Create the Connection Configuration File
    • Deploy the WAR
    • Web Application Descriptor
• Positioning Calendar on the Page
• Using Themes
• Designing a New Template
• Localization
  • Multilanguage Support
  • Localizing Individual Calendar Properties
• Client-Server Interaction
  • Requesting Events
  • Creating, Updating and Deleting Events on the Server
    • Create an Event
    • Modify an Event
    • Delete an Event
  • Creating, Adding and Modifying Calendars on the Server
    • Create a New Calendar
    • Add a Calendar
    • Modify a Calendar
• Events Handling
• Input Data Format
  • Calendar Object Format
  • Access Control List Object
  • Event Object Format
  • Recurrence Rule Object Format
  • Alarm Object Format
  • Organizer Object Format
  • Attendee Object Format

Installation Process of the PHP Version

Requirements

• PHP 5.x and later
• Any database server supported by ADOdb, for example, mysql 5
• ADOdb Library (http://adodb.sourceforge.net/)
• Zend Framework (http://framework.zend.com/download)
• Zapatec Ajax Suite

Unzip Files to Your Web Folder

Once you downloaded the TAR archive, unpack it to the web directory. When it is done, your application needs to be able to access ADOdb and Zend Framework libraries.

Access Database Libraries

To access framework classes, provide the path to the Zend Framework library in your PHP include_path. In case you plan to use non-MySQL database server, insert the path to the ADOdb library into your include_path. Though, it is not required if you want to use MySQL database server as far as the limited ADOdb is provided in the php_calendar/includes folder.

Migration to a Different Database

To migrate to another database, perform the following steps:

1. First, check if you have the ADOdb library installed on your local machine. Otherwise, download it from http://adodb.sourceforge.net/#download, and then unpack all the files into the php_calendar/includes directory.
2. After that, in the php_calendar/includes/loader.inc.php file, provide a path to the ADOdb library. See the code below for details:

   include('adodb/adodb.inc.php');

3. Finally, in the php_calendar/includes/config.inc.php file, define the configuration for a new database.

Create a Database on Your Database Server

Create a new database and import the dump from the sql/database.sql file into it.

Setup Configuration File

The includes/config.inc.php configuration file should be set up using the format described below.

To provide the database user's password:

$_CONFIG['db'] = "driver://user:password@server/database?persist";

To set the database user's password if you are using MySQL:

$_CONFIG['db'] = "mysql://user:password@server/database?persist";

To define a from name and email that will be used while sending notifications and approving requests:

$_CONFIG['fromName'] = 'Calendar';
$_CONFIG['fromEmail'] = 'calendar@localhost';

Set Scheduled Tasks

Set the task on a time-based scheduling service, such as cron, that will run the "php /path/to/ecal/calendar.php sendnotifications" command. This command checks the calendar for events with reminders and if finds, sends e-mail notification to the user.

Include Zapatec Suite

Place Zapatec Suite (with zpicalendar) into the /resources/js/zapatec/ project folder.

Installation Process of the Java Version

Requirements

• Java 2 SDK 1.4.* or later version of Java
• Tomcat 5.0. If you're using Java 5 or Java 6, you can install later versions of Tomcat.

Install from WAR

Create the db Schema

Initialize database using db Schema that you receive as a part of installation instructions.

Create the Connection Configuration File

Create the connection.properties text file at any location.
It should contain the following data (correct for your database) server:

engine=mysql
host=jdbc:mysql://localhost/
database=harmony
user=harmony
password=harmony

Deploy the WAR

Place calendar.war in the webapps directory, and deploy the WAR file.

Web Application Descriptor

Now, you need to edit the web.xml file to tell the application where the above connection.properties file resides.

Located at the project root: /resources/WEB-INF/web.xml.
Specify the path to the connection configuration file:

<init-param>
	<param-name>jdbc_connection</param-name>
	<param-value>/var/zapatec/harmony/connection.properties</param-value>
</init-param>

Positioning Calendar on the Page

You can control the calendar position on the page using autoresize and container options. To resize your calendar to the window size, set the autoresize option to TRUE. In case this behavior is not desirable, set this option to FALSE, and then in the template file specify calendar dimensions using width and height parameters. The container option is used to define an ID of the container element with the Events Calendar widget or a reference to it. This option is also useful when you want to add a new div element on the page, for example, to the left of the calendar.

Using Themes

The Events Calendar themes can help you create a well-designed calendar for viewing in your browser. A theme controls the look and the layout of your calendar - that is, how the calendar items appear, how an element looks when it is selected, background colors, fonts, and so on. Events Calendar provides multiple themes residing in the Themes folder that can be easily used to control look and feel of your calendar. You can also choose to customize the existing theme files and save them separately under the same folder. To apply any of the predefined themes as well as newly created ones, use the theme option and specify the desired theme name as a value for it. If the theme option is not specified, the default.css file in the Themes folder is used. For your theme proper functioning, insert the following style path before the ending </head> tag:

<link type="text/css" rel="stylesheet" href="../themes/default.css"/>
<script type="text/javascript" src="../src/zpicalendar.js"></script>

It is also possible to control the mini-calendar look using themes. You can use any of the themes designed for the Zapatec Calendar widget by providing the relative path to it in the calendarTheme option. Zapatec Calendar widget provides the vast range of the themes that reside in the Themes folder. For faster theme initialization, you need to insert the following calendar style path in the header and use the calendarTheme option for defining the theme name.

<link type="text/css" rel="stylesheet" href="../../zpcal/themes/winter.css"/>
<script type="text/javascript" src="../../zpcal/src/calendar.js"></script>

You can also use themes for pop-up windows, dialog boxes, confirmation windows, etc. For this purpose, include the style path to the Windows widget themes before the ending </head> tag. The code below will help you to do this:

<link type="text/css" rel="stylesheet" href="../../zpwin/themes/minimal.css"/>
<script type="text/javascript" src="../../zpwin/src/window.js"></script>

Using a custom theme, you can give your calendar a strong brand identity as well as a unique look.

Designing a New Template

Zapatec Events Calendar offers multiple HTML templates that can be easily edited with any HTML editor and adjusted to suite your personal requirements to your calendar design.
For the ability to use templates, you need to embed the Template widget module into you page. See the following code for details:

<script type="text/javascript" src="../../zptemplate/src/zptemplate.js"></script>

By default, the default.html template is used. To choose a different template for your calendar, use the templateFile option that sets absolute or relative path to the template file. For example, default value: '.../templates/default.html'. If you specify the template name in the templateFile option instead of URL, you need to use the templateFilePath option that defines the URL to the templates directory. To associate template IDs from the template file with template names, use the templates option. This option should receive an object in the following format:

{
 "main": "zpWidgetTemplateMain",
 ...
}
where "main" is the template name and "zpWidgetTemplateMain" is the template ID in the templates file.

In case you are mostly satisfied with the predefined template but still you want to make some changes, go to the Template folder, open any of the files in the HTML editor, and then make all modifications you need to the calendar design.

The calendar template consists of the following subordinate templates that can be separately changed:      

1. Main Table Template — contains classes that control the top bar (tab bar, button bar and message), the main table (grid container, event options form, container used for miscellaneous forms), the new event dialog box, the edit event dialog box and confirm dialog box.
2. Left Menu Template — controls the left menu calendar, My calendars and Other calendars lists
3. Attendee List Template — controls the list of guests who are invited for the event
4. Month Template — controls the calendar style for the Month view (column headers, vertical and horizontal rules)
5. Month Grid Cell Template — controls the style of cells in the Month view
6. Week Template — controls the calendar style for the Week view (column headers, days grid, row headers, vertical and horizontal rules)
7. Event Template — controls the style of events
8. All Day Event Template — controls the look of all-day events
9. Month Event Template — controls the style of events in the Month view
10. More Events Link Template — controls the style of the More Events link
11. Selectbox Template — controls the style of the select box
12. Add Calendar Form Template — controls the look of the form for adding a new calendar
13. Create Calendar / Calendar Details Form Template — controls the style of Create New Calendar / Calendar details form
14. Access Control List Line Template used in the Create Calendar Form — controls the access control list in the Create new calendar form

Localization

Multilanguage Support

Translation mechanism implemented in the Events Calendar is quite different from that in Widget. It uses a new Zapatec Dictionary library (utils/zpdict.js) that provides the ability to translate libraries and static functions and should be included into the head sections of your page. Basically, if you use the English language, no steps are needed. However, if your calendar needs to be presented in any other language, you should perform the following steps:

1. Include the zpdict.js module after zapatec.js
2. Embed language modules for each library (utils/lang/zpdate-fr.js)
3. Insert the language module for the iCalendar (zpicalendar/scr/lang/zpicalendar-fr.js)
4. Set the language option by providing two-letter language code used for widget initialization. Default: 'en'

If you want to use a different language (e.g. Spanish), which is not provided in the lang folder, copy zpdate-fr.js and zpicalendar-fr.js to new files, for example, zpdate-es.js and zpicalendar-es.js and replace the French equivalents to the English phrases with the Spanish ones. 

Localizing Individual Calendar Properties

Apart from the language localization, you may also need to adjust the date and time format as well as the first day of the week to match the certain locale. For doing this, you may use configuration options that are listed below:   

• The firstDayOfWeek option defines the first day of the week. This option receives a zero-based first day of the week. For example: 0 - Sunday; 1 - Monday. Default: 0. You can easily change it by providing another numeric value to suit your users' needs.
• To change the date format, use the formatDate option. The default format is '%m/%d/%y'.
• Setting the time format relevant to specific areas is done through the use of the formatTime option. The default format is '%l:%M/%P'.

The following table contains tokens that can be used to customize time and date formats:

Client-Server Interaction

All the functions for client-server interaction reside in the zpicalendar-server.js file.

For client-server interaction, use the commandScript option that receives URL of the server-side command script. The following CGI arguments can be passed to the script with the help of the POST method:

• getdata
• eventcreate
• eventmodify
• eventdelete
• calendaradd
• calendarcreate
• calendarmodify

These commands are passed using the command argument, e.g. command=getdata.

Requesting Events

To return events planned for the particular period of time, use the getdata command. Consequently, this command should be followed by the range argument (object passed to the Zapatec.ICalendar.callbackSource) that contains the start and end date of the definite time period in the YYYYMMDD format.
See the following for example on how to set the range argument:

range={"from":"20071201","to":"20071203"}

If getdata command is passed, the script must output source data for Zapatec ICalendar widget as a JSON string. If other than the getdata command is passed, the script must output the following object as a JSON string:

{
   error: [string, optional] human readable error description if error occurred during the command (other properties are ignored in that case),
   success: [string, optional] success message depending from command type,
   id: [string, optional] depending from command type for example ID of created event
}

Creating, Updating and Deleting Events on the Server

Create an Event

You can create events on the server through the use of the eventcreate command followed by a new event object that should be passed to the server script. For the event object format, see the Event Object Format section.

If the event was created successfully, the command receives the event ID from server and assigns it to the newly created event. Depending on the server response, zpICServerEventCreated is fired on success and zpICServerEventNotCreated — on error.

Modify an Event

To modify events on the server, use the eventmodify command. This method receives the modified event object as a parameter. See the Event Object Format section for details on the format of arguments that should be passed to this command. In case the event was successfully modified, zpICServerEventModified gets fired, if your attempt to modify the event on the server fails, zpICServerEventNotModified is fired.

Delete an Event

If you want to delete an event on the server, pass the eventdelete command to the server script followed by the event object to be deleted. The zpICServerEventDeleted is fired when you delete an event from the server, if the event cannot not be deleted, the server script fires the zpICServerEventNotDeleted event.

After you have created, modified or deleted an event, the Widget makes appropriate changes by updating the current view, and sends information about the event to the server. This is realized by sending new, modified or deleted events object to the command script in order to make relevant changes in the database. If the server operation was successfully performed, the server sends back the success message. If a change can affect multiple events, such as a global configuration change, the Events Calendar will reinitialize.

Creating, Adding and Modifying Calendars on the Server

Create a New Calendar

To create a calendar on the server, pass the calendarcreate command to the server script. As an argument, you should pass the calendar object in the following format:

{
    title: [string] calendar title,
    summary: [string] calendar description,
    where: [string] calendar location,
    color: [string] calendar color,
    defaultRole: [string] default access level,
    acl: [object] access control list (array)
}

The following is an example that creates a new calendar on the server:

Zapatec.ICalendar.prototype.serverCalendarCreate = function(oCalendar) {
	this.serverCalendarSend({
		calendar: oCalendar,
		eventSuccess: 'zpICServerCalendarCreated',
		eventError: 'zpICServerCalendarNotCreated',
		message: 'Creating calendar',
		command: 'calendarcreate',
		errorMessage: 'Calendar was not created'
	});
};

If the server operation was successfully performed, the server sends back the success message. The zpICServerCalendarCreated event fires on success, zpICServerCalendarNotCreated --- on error.

Add a Calendar

Use the calendaradd command that sends the calendar id to the server to add a calendar. This command receives a contact E-mail address as an argument.
Here is an example of the E-mail address format to be passed to the calendaradd command:

{
 email: [string] contact email
 }

If you successfully added a calendar on the server, the zpICServerCalendarAdded is fired, otherwise — zpICServerCalendarNotAdded.

Modify a Calendar

Modifying calendar details is realized through the use of the calendarmodify command. To make this command enter changes to the calendar properties in the database on the server, you should pass a calendar object with modified properties as an argument to it. The following calendar object format must be used for this purpose:

{
 id: [string] calendar ID on the server,
 author: [string] calendar author's e-mail,
 title: [string] calendar title,
 summary: [string] calendar description,
 where: [string] calendar location,
 color: [string] calendar color,
 defaultRole: [string] default access level,
 acl: [object] access control list (array)
 }

If the calendar was successfully modified, zpICServerCalendarModified gets fired. In case an error occurred, the server script fires zpICServerCalendarNotModified.

Events Handling

In addition to events fired from the base Widget class, the following events are fired during interaction with the server:  

Use events to make your Events Calendar respond to the certain actions performed by the user by executing specific functions. This is possible through the use of the eventListeners option. For details on setting this option, see the code below:

{
 [string] event name: [function or object] event listener or array of event listeners
 ...
 }

Input Data Format

Currently Events Calendar accepts only JSON source. This section provides information on input data formats specific for each object.

Calendar Object Format

The Calendar object is used to configure calendar ID in the database, its name, color, calendar owner, calendar access level for all the users that are not specified in the access control list, calendar description and location. This object can be extended using access control list and events object.  
For creating or modifying calendars, you should pass the object in the format described below:

{
     calendars: [
       {
         id: [string] calendar ID in the database,
         title: [string] calendar name,
         color: [string] calendar color, one of:
             '#A32929', '#B1365F', '#7A367A', '#5229A3', '#29527A', '#2952A3',
             '#1B887A', '#28754E', '#0D7813', '#528800', '#88880E', '#AB8B00',
             '#BE6D00', '#B1440E', '#865A5A', '#705770', '#4E5D6C', '#5A6986',
             '#4A716C', '#6E6E41', '#8D6F47',
         cn: [string] common or displayable name of the calendar owner,
         email: [string] email of the calendar owner,
         accessLevel: [string] calendar access level, one of: 'owner', 'read',
         summary: [string] calendar description,
         where: [string] calendar location,
         selected: [boolean] true - selected (events are visible), otherwise - not selected (events are not visible),
         defaultRole: [string] access level for all users not specified in the access control list, one of: 'none' - do not share with everyone;
             'read' - share all information on this calendar with everyone; 'freebusy' - share only my free/busy information (hide details),
         acl: [
           {access control list object},
           ...
         ],
         events: [
           {event object},
           ...
         ]
       },
       ...
     ]
}

Access Control List Object

This object requires the E-mail address and the participation role of the user in the particular calendar (owner; editor; read; freebusy).    

{
 cn: [string, optional] user's name,
 email: [string] user's email,
 role: [string] one of: 'owner' - make changes and manage sharing, 'editor' - make changes to events,
'read' - see all event details, 'freebusy' - see free/busy information (no details)
}

Event Object Format

By providing this object, you can assign a unique ID to the event, set the event description, define the place of the event, attribute your event to the calendar you need, specify its start and end dates, set user status during this event and determine its access classification. The event object can be extended with the help of recurrence rule, alarm, organizer and attendee objects.   

{
 id: [string] event ID in the database,
 calendarId: [string] calendar ID in the database,
 dtstart: [string, optional] start date in RFC 2445 format,
 dateIsoStart: [string, optional] start date in ISO 8601 format,
 dtend: [string, optional] end date in RFC 2445 format,
 dateIsoEnd: [string, optional] end date in ISO 8601 format,
 summary: [string, optional] event description,
 rrule: [object, optional] recurrence rule,
 DTSTART: [string, optional] start date of recurrence in RFC 2445 format,
 where: [string, optional] where,
 description: [string, optional] description,
 alarms: [object, optional] array of alarm objects,
 transp: [string] transparency (show me as), one of: 'transparent' - free, 'opaque' - busy,
 privacy: [string] access classification, one of: 'default', 'public', 'private',
 organizer: [object, optional] organizer of an event,
 attendees: [object, optional] array of attendee (guest) objects
}

RFC 2445 format examples: 20071210T080000Z, 20071210. See http://tools.ietf.org/html/rfc2445#section-4.8.7.2 for details.
ISO 8601 format examples: 2007-11-05T13:15:30Z, 2007-11-05. See http://en.wikipedia.org/wiki/ISO_8601 for details.
One of 'dtstart' or 'dateIsoStart' must be defined.
One of 'dtend' or 'dateIsoEnd' must be defined.

Recurrence Rule Object Format

The recurrence rule object extends the event object and sets the frequency of regularly occurring event, the interval between event recurrences and the date after which the event should not be repeated.    

{
 FREQ: [string] frequency one of: 'DAILY', 'WEEKLY', 'MONTHLY', 'YEARLY',
 INTERVAL: [number] repeat interval,
 BYDAY: [object] applicable for FREQ == 'WEEKLY' only; array of days when event occurs; example: ['TU', 'TH'] - every Tuesday and Thursday,
 BYDAY: [string] applicable for FREQ == 'MONTHLY' only; week number followed by day abbreviation; example: 3WE - every third Wednesday,
 BYMONTHDAY: [number] applicable for FREQ == 'MONTHLY' only; month day when event occurs; example: 4 - every 4-th day of month,
 UNTIL: [string] date in RFC 2445 format until event should trigger
}

Day abbreviations are: 'SU', 'MO', 'TU', 'WE', 'TH', 'FR', 'SA'.
Only one of "BYDAY" or "BYMONTHDAY" should be defined at the same time.

Alarm Object Format

The alarm object can be defined inside the event object to set how the user should be reminded of the upcoming event and the time before an event in minutes when the notification is to be received. You may choose to be reminded by the alert box, via E-mail or SMS.   

{
 action: [string] one of: 'alert', 'email', 'sms',
 duration: [number] how far in advance of the event the alarm should be triggered in minutes
}

Organizer Object Format

The organizer object can extend the event object and is used for specifying the common or display name and E-mail address associated with the event organizer.

{
 cn: [string, optional] common or displayable name,
 email: [string] email
}

Attendee Object Format

This object sets the guest's name and E-mail address, defines the status of the attendee's participation in the particular event (invited; accepted; declined; tentative) and identifies the expectation of a reply from the calendar user specified by the cn option.

{
 cn: [string, optional] common or displayable name,
 email: [string] email,
 partstat: [string] the status of the attendee's participation one of: 'invited' - needs action, 'accepted', 'declined', 'tentative',
 rsvp: [boolean, optional] for indicating whether the favor of a reply is requested
}