a LuxSoft product

LuxCal Event calendar

Installation Guide

Table of Content

  1. Installation of Updates

  2. New Installation

    1. Requirements

    2. Installation Steps

    3. Configuring / Customizing the calendar

    4. My Calendar doesn't Work

  3. Calendar Configuration

    1. LuxCal Version Number and Database Credentials

    2. Installing Automatic Periodic Functions

    3. Installing a New Language

    4. Using SMTP Mail for Reminders and Reports

  4. Installing Additional Calendars

    1. Calendars with an Individual Database

    2. Calendars Sharing the Same Database

  5. Adding the Calendar to an Existing Web Page

    1. Link to the Calendar

    2. Add a Sidebar with Upcoming Events

    3. Embed a Mini Calendar

    4. Embed the Full Calendar

    5. Embed One Specific Calendar View Without Navigation Bar

    6. 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:

  1. Create a MySQL database on the server to store the LuxCal calendar data. Ask your hosting provider if they provide a tool for you to do this.

    For later use, remember the name of the database server (host name), the username and password required to log in to the database server and the database name to access the database.

  2. Download and unzip the latest version of LuxCal (file: luxcalxxx.zip, where 'xxx' is the version number) in a temporary location. This file contains the following two compressed files: luxcalxxx-calendar.zip and luxcalxxx-toolbox.zip. Unzip the file luxcalxxx-calendar.zip and upload all files and folders to a web accessible folder on the server where you wish to install LuxCal. Keep the file luxcalxxx-toolbox.zip for possible later use.

  3. With your Web browser browse to the folder of the LuxCal installation; it will redirect you to the install.php script and show the Installation page.

  4. On the Installation page enter the database details and the administrator name, e-mail address and password and click "Install." The script will generate the necessary tables in the database and saves your LuxCal version number and the database credentials in a file called lcconfig.php in the calendar's root folder.

  5. Launch the calendar by browsing to the calendar's URL to ensure the calendar displays properly.

  6. Keep a backup copy of the lcconfig.php file. It contains the LuxCal version number and the parameters for the MySQL database.

Note: The file luxcalxxx-toolbox.zip (see step 2 above) contains the LuxCal tools which should be kept for later use and which should be uploaded to the calendar root folder only when needed.

c. Configuring / Customizing the Calendar

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. 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, and many other things.

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.

The user interface style (colors, fonts, etc.) can be customized by editing the lctheme.php file in the css folder. This can be particularly useful when the calendar is embedded in an existing web page and should match the parent web page style.

d. My Calendar doesn't Work

The two most frequent problems are:

With the lctools.php script, which you can find in the LuxCal toolbox, you can check if your LuxCal calendar installation is ready for use or to further analyse above problems

3. Calendar Configuration

a. LuxCal Version Number and Database Credentials

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

The file lcconfig.php contains the following data (in the form of PHP variables):

  1. The version number of the LuxCal installation. For example "3.2.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.

  2. The following database credentials:

    • 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: This variable is used as a prefix for the database table names. If only one calendar has been installed, this prefix will automatically be set to 'mycal'. If more than one calendar has been installed sharing the same MySQL database, this table prefix is the one for the default calendar.

b. 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 folder 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.

- Daily Export of Events in iCalendar format

When enabled on the admin's Settings page, each day a file in iCalendar format (.ics extension) will be created in the 'files' folder with all events occurring in the time range -1 week until +1 year. These files can be imported by other calendar applications. The name of the file is the calendar name with the characters ' ','/','\','?','*',':',';','{','}' replaced by an underscore and diacritics removed. A new file will overwrite the previous one.

- 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).

c. 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). This is an excellent free text editor!

d. Using SMTP Mail for Reminders and Reports

Reminder emails and email reports (triggered by a cron job) are sent by default via the PHP mail system. If however, email authentication is required, the admin can choose on the Settings page, under General, to use an SMTP mail server.

Before choosing SMTP mail on the admin's Settings page, the following SMTP mail server parameters must be specified on the Settings page:

Note: TLS (Transport Layer Security) is not supported.

If you don't know what parameters to use, ask your mail provider for the correct parameters.

Example: To use a gmail SMTP server with your "my.mail@gmail.com" email address, the SMTP settings on the Settings page should be as follows:

The tool called "smtptest.php", which you can find in the LuxCal toolbox, can be used to test the SMTP settings specified on the Settings page.

4. Installing Additional Calendars

During the initial installation of the calendar one calendar will be installed in your MySQL database. The tables of this calendar will be prefixed with the string "mycal_" and the calendar title will be "My Web Calendar".

There are two ways to add additional calendars:

  1. After the initial installation, install the calendar a second time, a third time, etc., each time in it's own folder. This way of installing will require a MySQL database per calendar. To upgrade later to a newer calendar version, you will have to upgrade each individual calendar.
  2. After the initial installation, use the LuxCal tool lctools.php from the LuxCal toolbox and launch the tool via your browser. This tool can very efficiently create additional calendars, sharing the same database by prefixing the calendar tables with a unique text string per calendar. To upgrade later to a newer calendar version, you will only have to upgrade one installation.
a. Calendars with an Individual Database

To install more than one calendar, each calendar using its own database, the installation steps described in section 2 should be repeated for each calendar. For each next calendar, a new MySQL database should be created and the calendar should be installed in a new folder.

This process can be repeated as many times as needed. The disadvantage of installing several individual calendars however is that you will need one MySQL database per calendar and when upgrading to a new calendar version, each individual calendar needs to be upgraded.

The different calendars can be started by browsing to the relevant calendar folders.

b. Calendars Sharing the Same Database

To install additional calendars, all sharing the same database, should be done via the toolbox tools 'lctools.php'. This file is part of the LuxCal toolbox and should be uploaded to the calendar root folder and be started via your browser. When selecting one of the available tools a dedicated explanation will be displayed, with detailed instructions on how to use the selected tool.

The advantages of installing multiple calendars sharing the same database are: Only one single database is needed and when upgrading to a newer LuxCal version, just one single upgrade for all calendars.

One calendar will be set as the default calendar. This calendar will start when browsing to the calendar folder. The other calendars can be started by adding '?cal=xxx' to the calendar URL, where 'xxx' is the calendar ID.

5. Adding the Calendar to 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. Add a Sidebar with Upcoming Events or ToDo list

A sidebar with public upcoming events or a ToDo list for the coming x days can be added to your web page. The sidebar is placed in a <div>-tag container, can be placed at any location and is fully customizable. An example is shown on the LuxCal Demo page of the LuxSoft web site. The sidebar can be added to your web page by adding the following lines of code to the <head>-section of your web page:

<link rel="stylesheet" type="text/css" href="mycalendarfolder/css/css_sbar.php"> <script type="text/javascript" src="mycalendarfolder/common/toolbox.js"></script>

and adding the following lines of code to the body of your web page:

<?php $sbClass = {sidebar class}; * $sbContent = {sidebar content}; * $sbHeader = {sidebar title}; * $sbCatsIn = {list of categories to include}; * $sbCatsEx = {list of categories to exclude}; * $sbUsersIn = {list of users to include}; * $sbUsersEx = {list of users to exclude}; * $sbMaxNbr = {max. number of events to show}; * $sbUpDays = {max. number of days to show}; * $sbCal = {calendar ID}; * include './mycalendarfolder/lcsbar.php'; ?>

* These parameters are optional and can be omitted. See explanation hereafter.

Explanation of the lines of code:

All parameters indicated by {....}, including the braces, are text strings between single or double quotes.

In the above lines of code you should replace mycalendarfolder by the name of the root folder of your calendar installation.

The file css_sbar.php contains the default style for the sidebar container <div>, which should be tailored to your needs. In the same file you can customize the style, colors, fonts, etc. of the sidebar content. The title of the sidebar can be set per sidebar and the events in the sidebar can be filtered on the event sequence number and/or user ID. This allows for more than one sidebar per site, each with its own title and a different list of events.

Example of two sidebar definitions for the same website which are complementary:

<?php $sbClass = 'sideBar1'; $sbHeader = 'Birthdays/Holidays'; $sbCatsIn = '2,4'; include './mycalendarfolder/lcsbar.php'; ?> <?php $sbClass = 'sideBar2'; $sbHeader = 'All other events'; $sbCatsEx = '2,4'; $sbUpDays = '7'; include './mycalendarfolder/lcsbar.php'; ?>

For each event the following will be displayed: date, time and title. Via the admin's Settings page, under "Stand-Alone Sidebar", you can choose whether further event details should be shown in a pop-up box (like in the full LuxCal calendar) when hovering an event and if URLs from the event description (if any) should be displayed in the sidebar as a hyperlink. On the same Settings page you can specify the number of days to look ahead for events in the sidebar.

The sidebar is using the database and tools of the full calendar and therefore the full calendar should be present in the "mycalendarfolder" (see code above).

c. 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 id="lcmini" src="http://www.mysite.xx/luxcal/lcmini.php"></iframe>

Via the CSS styles of your site, the id lcmini can be used to position and define the style of the iframe containing the mini calendar. The style for id lcmini could for instance look as follows:

#lcmini { position:absolute; right:100px; top:15%; width:210px; height:233px; overflow:hidden;}

If you want the height of the mini calendar to vary automatically depending on the month to display (4, 5 or 6 weeks) you should add the following JavaScript code, which dynamically adjusts the height of the iframe, 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.

d. 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 id="luxcal" src="http://www.mysite.xx/luxcal/?cP=2"></iframe>

With parameter cP the default view can be set (e.g. year: cP=1, month: cP=2, . . . ,upcoming: cP=7)

Via the CSS styles of your site, the id luxcal can be used to position and define the style of the iframe containing the luxcal calendar. The style for id luxcal could for instance look as follows:

#luxcal { width:80%; height:800px; margin:20px; border-style:solid; border-width:1px; border-color:grey; }
e. 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"></iframe>

Without navigation bar 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 id="luxcal" src="http://www.mysite.xx/luxcal/?hdr=0&cP=7&cL=Francais"></iframe>

Via the CSS styles of your site, the id luxcal can be used to position and define the style of the iframe containing the LuxCal calendar. The style for id luxcal could for instance look as follows:

#luxcal { width:80%; height:800px; margin:20px; border-style:solid; border-width:1px; border-color:grey; }

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.

f. 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 to 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 2014 - powered by LuxSoft