a LuxSoft product

LuxCal Event calendar

Installation Guide

Table of Content

  1. Installation of Updates

  2. New Installation

    1. Requirements

    2. Installation Steps

    3. My Calendar doesn't Work

  3. Calendar Configuration Variables

    1. LuxCal Version Number and Database Credentials

    2. Calendar Settings

    3. Installing Automatic Periodic Functions

    4. Installing a New Language

  4. Managing the Calendar

    1. Event Categories

    2. Calendar Users

    3. Calendar Database

    4. CSV File Import

    5. iCal File Import/Export

    6. Calendar Settings

  5. Embedding the Calendar in an Existing Web Page

    1. Link to the Calendar

    2. Embed a Mini Calendar

    3. Embed the Full Calendar

    4. Embed One Specific Calendar View Without Navigation Bar

    5. Single Sign On (SSO)


1. Installation of Updates

To upgrade to a new version of the LuxCal Event Calendar follow the instructions in the file "release_notes_luxcal_xxx.html" (where xxx indicates the release).

2. New Installation

a. Requirements

For the installation of the LuxCal Event Calendar on the server of your hosting provider, you will need:

b. Installation Steps

To install the LuxCal Event Calendar on the server of your hosting provider, follow the next steps:

c. My Calendar doesn't Work

The two most frequent problems are:

On the Download Page of the LuxSoft site you can download the LuxCal configuration tool which can be used to check if your LuxCal calendar installation is ready for use or to further analyse above problems.

3. Calendar Configuration Variables

a. LuxCal Version Number and Database Credentials

During the LuxCal installation process a file called lcaldbc.dat is created and stored in the root directory of the calendar. If, when launching the calendar, the file lcaldbc.dat is not present in the calendar root directory, it is assumed the calendar has not yet been installed and consequently the calendar's installation script will be started.

The file lcaldbc.dat contains the following three lines:

  1. The text "LuxCal".

  2. The version number of the LuxCal installation. For example "2.7.0". This version number is used by the calendar to check if the current calendar installation is up-to-date with the installed calendar files and to determine if the upgrade script should be run.

  3. The following database credentials in encrypted form:

    • host name: This is the name of the database server and is often called "localhost".

    • user name: The database user name is the user name required to connect to the database. This user name was chosen when the database was created on the server of your ISP. Note: This user name should not be confused with the admin's user name to log in to the calendar!

    • password: The database password is the password required to connect to the database. This password was chosen when the database was created on the server of your ISP. Note: This password should not be confused with the admin's password to log in to the calendar!

    • database name: This is the name of the database on the database server which will be used by the LuxCal calendar to store all its data. The calendar data is stored in the following tables: events, users, categories and settings.

    • table prefix: If not blank, this variable is used as a prefix for the database table names. This may be useful if you are short of databases and want to share the database with other applications, or if you want to use several separate LuxCal calendars. The prefix could for instance be lc1_ or db1_, etc.

b. Calendar Settings

The calendar settings which are automatically generated during the installation process are stored in the settings table of the database. All settings can be changed at a later stage by the calendar administrator via the Settings page in the drop down menu on the navigation bar at the top right corner of the screen.

For those interested in technical details: The following are explanations of the PHP variables stored in the settings table of the database:

c. Installing Automatic Periodic Functions

The following automatic periodical functions are available:

To make the automatic periodical functions work, a cron job needs to be created on the server (or on an external server), which executes the file lcalcron.php, in the root directory of the calendar, daily at approx. 2:00am. For cron job details see the header of the lcalcron.php file.

If you are not familiar with cron jobs, ask your hosting provider for help.

- The Email Notification Feature

For events entered in the calendar the user can choose to receive an email reminder (notification) one or several days before the event is due. When chosen, for recurring events (e.g. birthdays) an email notification will be sent to the user the selected number of days before each occurrence of the event. Imagine: never forget to buy flowers for your (girl)friend's birthday anymore!

- Receiving Calendar Changes by Email

In a multi-user environment it could be useful to be aware of changes being applied to the calendar content, i.e. a list with events added, edited and deleted. Such a list can be called up via the options panel. It is however also possible to have a list with changes automatically sent daily to one or more email addresses.

Via the Settings page the administrator can specify the number of days to look back for changes and a list with email addresses. If the number of days to look back for changes is set to 0 (zero), no emails with changes will be sent.

- Automatic Deletion of Expired Events

Events which due date has past can automatically be deleted. Via the Settings page the administrator can specify the number of days after an event's due date when an event will automatically be deleted. If the number of days is set to 0 (zero), no events will be deleted.

Note: deleted events are flagged "deleted"; definitively removing deleted events from the database is done via the admin's Database page.

- Automatic Deletion of Expired (unused) User Accounts

The account of users who have not logged in during a certain number of days can automatically be deleted. Via the Settings page the administrator can specify the number of 'no login' days after which the user account will be deleted. If the number of 'no login' days is set to 0 (zero), no user accounts will be deleted.

This function can be particularly useful when users are allowed to self-register (this feature can be switched on/off on the admin's Settings page).

d. Installing a New Language

= Note: in the following text the part {language} (including the braces) of the file names represents the name of the relevant language. =

A new language for the user interface of the LuxCal calendar can be installed as follows:

IMPORTANT NOTE: When using special characters (e.g. accents) in the language files, the ui and ug files can best be saved with character encoding: utf-8 without BOM (BOM = Byte Order Mark). If your text editor does not support utf-8 without BOM, you can download and use Notepad++ (Notepad++ on Sourceforge).

4. Managing the Calendar

Managing the LuxCal calendar is the responsibility of the calendar administrator, who has all calendar access rights.

In order to define users, to set up categories for the calendar, to change configuration settings and to add events, you must select Log In in the navigation bar at the top right corner of the screen. Enter the administrator name or email address and password you specified during the installation, and log in. On the right side of the navigation bar the administrator drop down menu will be displayed.

a. Event Categories

A good place to start in managing your calendar is to create a number of categories for your events, each with its own color. Adding categories with different colors - though not required - will greatly enhance the views of the calendar. Categories can be for example: meeting, important, holiday, birthday, etc.

The initial installation has only one category which is named "no cat". To manage categories, select Categories in the administrator drop down menu. This takes you to a page with a list of all categories where you can add new categories and edit or delete current categories.

When adding / editing events the defined categories can be selected from a pull down list. The order in which categories are displayed in the pull down list is determined by the Sequence field on the Categories page.

The field Repeat can be used to pre-define recurring events. A category "birthday" or "anniversary" can be set to repeat every year. If a repeat value is specified, all events defined in this category will repeat as specified. The repeat value specified here will overrule possible user 'repeat' settings.

The checkbox "Public" can be unchecked to exclude certain event categories from being viewed by the "Public User" and from the RSS feeds.

One or two check marks can be activated which will be displayed in front of the event title for all events in this category. The user can use these check marks to flag events, for example, as "approved" or "completed"

The fields Text Color and Background define the colors used to display events in the calendar assigned to this category.

b. Calendar Users

The Users menu in the navigation bar allows the calendar administrator to add and edit users, their rights for using LuxCal and their user interface language. There are two main areas that can be edited, i.e. the name / e-mail address / password area and the access rights area. Possible access rights are: "View", "Post Own", "Post All" and "Admin". It is important to use a valid email address for each user to be able to receive email notifications of due dates of events. For each user the default user-interface language can be specified. Whenever a user logs in, the user-interface language will be set to this language.

The initial installation has two users defined. One is the Public Access user, who initially has "view" access and the other is the calendar administrator, with the administrator name, email address and password specified during the installation. The administrator has all access rights.

Unless the calendar administrator has given "View" access to Public Access users, users must log in to use the calendar using their name or email address and password. Depending on the type of user, a user can have different access rights which can be set by the calendar administrator.

If the administrator has enabled, on the Settings page, user self-registration, users can register themselves via the Login page. Self-registered users have the access rights specified by the administrator on the Settings page.

c. Calendar Database

The Database menu in the navigation bar allows the calendar administrator to start the following functions:

d. CSV File Import

CSV (Comma Separated Values) text files with event data can be imported into the LuxCal calendar. This function can for instance be used to import a CSV file with event data exported by MS Outlook. The dialogue to import CSV files is opened by selecting CSV Import from the admin drop-down menu in the navigation bar.

The CSV file contains one line per event and each line contains a number of fields each separated by a comma (or any other unique character). The order of the fields in each line of the CSV file is: title, venue, category id, date, end date, start time, end time and description. The first line of the CSV file is ignored by the import function and can be used for column descriptions (default in MS Outlook exports).

Sample CSV files - with different date/time formats - can be found in the files/ directory of the LuxCal Calendar installation and have the file extension ".csv".

e. iCal File Import/Export

Events from iCalendar files can be imported into the LuxCal calendar. The content of the iCal file to be imported must meet the [RFC5545 standard] of the Internet Engineering Task Force. The LuxCal calendar can also export events into an iCal file which can be downloaded by the calendar administrator. The dialogue to import/export iCal files is opened by selecting iCal Import / iCal export from the admin drop-down menu in the navigation bar.

This function can for instance be used to back up the events of your LuxCal calendar, or to exchange events with other calendars, e.g. to import public holidays available in iCal format on the internet. Please note that some LuxCal event fields are not supported in the iCal format (e.g. private event, notify, email addresses) and consequently are not copied to the iCal file. Some iCal event repetition rules are not supported by the LuxCal calendar; these events will be displayed and earmarked as such, but will not be added to the calendar.

Various sample iCal files can be found in the files/ directory of the LuxCal Calendar installation and have the file extension ".ics".

f. Calendar Settings

The Settings page in the administrator's menu on the navigation bar can be used to easily change the calendar's configuration settings which are stored in the settings table of the database (see section 3 above). These settings, for instance, define the calendar title, the time zone, the language file to be used for the user interface, the default initial view when the calendar is started, the number of weeks/months displayed in the various views, the date and time format, etc.

IMPORTANT: Currently the TimeZone is set to "Europe/Amsterdam". If you are in a different time zone, change the TimeZone to your local time zone. See the PHP Supported Timezones for possible values.

5. Embedding the Calendar in an Existing Web Page

To use the calendar on an other web site, the following possibilities are available:

a. Link to the Calendar

To link to the LuxCal calendar in an existing web page and open it in a new window, the following HTML code can be used:
<a href="http://www.mycalsite.xx/luxcal/" target="_blank">Go To My Calendar</a>.

b. Embed a Mini Calendar

A mini calendar with a (minimum) width of 160px can be embedded in your web site. An example is shown on the LuxCal Demo page of the LuxSoft web site. The mini calendar can be displayed in an inline frame (iframe) using the following HTML code:

<iframe class="lcmini" id="lbl-lcmini" src="http://www.mysite.xx/luxcal/lcmini.php" width="210px" height="233" scrolling="no"></iframe>

Via the CSS styles, the class lcmini can be used to position and define the style of the iframe containing the mini calendar.

The height of the mini calendar varies depending on the month to display (4, 5 or 6 weeks) and therefore the following JavaScript code, which dynamically adjusts the height of the iframe, must be added to the <head> section of the parent web page:

<script type="text/javascript">
function setHeight(newHeight){var plus=(document.all)?8:0; document.getElementById('lcmini').style.height=newHeight+plus+'px';}
</script>

Please note: Automatic adjusting of the iframe height only works if the calendar is located in the same domain as the parent page. If not, the iframe height is set to cope with displaying 6 weeks.

c. Embed the Full Calendar

To embed the full LuxCal calendar in an existing web page, an inline frame (iframe) can be used. This can for example be done with the following HTML code:

<iframe class="luxCal" src="http://www.mysite.xx/luxcal/?cP=2" width="80%" height="800px"></iframe>.

With parameter cP the default view can be set (e.g. year: cP=1, month: cP=2, . . . ,upcoming: cP=5)
Via the CSS styles, the class luxCal can be used to position the iframe at the desired location and to set the width and height to fit your needs.

d. Embed One Specific Calendar View without Navigation Bar

To embed the LuxCal calendar without navigation bar, the parameter hdr=0 should be added to the URL as follows:
<iframe src="http://www.mysite.xx/luxcal/?hdr=0&cP=2" width="80%" height="800"></iframe>.

The visitor will not be able to navigate the calendar and select other views. The following parameters can be added to select the view to display and the user-interface language:


For example the HTML code to show the Upcoming Events page without navigation bar, in the French language looks as follows:
<iframe src="http://www.mysite.xx/luxcal/?hdr=0&cP=5&cL=Francais" width="80%" height="800"></iframe>.

Via the CSS styles the iframe can be positioned at the desired location and the width and height can be set to fit your needs.


Important:
The parameter hdr=0 is remembered via the PHP session mechanism; this means that if you access the embedded calendar without navigation bar, then thereafter, when accessing your normal (not-embedded) calendar when your session is still active (max. one hour) you will also see no navigation bar. This can be solved by adding the parameter hdr=1 to the URL of your normal calendar.

e. Single Sign On (SSO)

When the calendar is embedded in a PHP-based website where users have to log in, users logged in on the parent website can be logged-in in the calendar automatically in a secure way, using PHP sessions.

To achieve this the parent website scripts should:


Because PHP session data are stored on the server, the user name / email address are not visible to the users.


 - End of Installation Guide -

design 2012 - powered by LuxSoft