Installation Guide - SQLite Version
Table of Content
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 is the calendar version number).
2. New Installation
a. Requirements
For the installation of the LuxCal Event Calendar on the server of your hosting provider, you will need:
A web accessible folder on a web server to install the LuxCal files.
The web server should be able to run PHP-scripts (PHP 5.3 or higher).
b. Before You Start
The SQLite database data is stored in a file located on your web server. The location of this database file is important. If it's located in a web-accessible folder (document root or lower) and no special measures are taken, this database file could be found, downloaded, and exploited. The path to the database file(s) can be specified during the installation process and is stored in the lcconfig.php file in the calendar root directory. To prevent unauthorized download of your database file(s), the following measures can be taken:
- During the installation process specify a not web-accessible folder for your database file(s). Most providers allow you to use folders above your document root, which are not web-accessible.
- If you're not allowed to use folders above the document root and your server is an Apache server,
create a file called ".htaccess" with the following content:
Deny from all
and store this file in the database folder.
c. Installation Steps
To install the LuxCal Event Calendar on the server of your hosting provider, follow the next steps:
Download and unzip the latest version of LuxCal (file: luxcalxxx.zip, where 'xxx' is the calendar 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.
With your Web browser browse to the folder of the LuxCal installation; it will redirect you to the installxxx.php script ('xxx' is the calendar version number) and show the Installation page.
On the Installation page read the instructions and enter the calendar and administrator details and select "test" If all tests passed successfully, select "install/save". The script will create the SQLite database in the specified folder, define the necessary database tables and save your LuxCal version number and the database parameters in a file called lcconfig.php in the calendar's root folder.
Launch the calendar by browsing to the calendar's URL to ensure the calendar displays properly.
Keep a backup copy of the lcconfig.php file. It contains the LuxCal version number and the parameters for the 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.
d. Configuring / Customizing the Calendar
The Settings page in the administration 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 style of the parent web page.
e. My Calendar doesn't Work
The most frequent problems:
The calendar shows a blank page
Often this problem is caused by the fact that the calendar cannot connect to the database, for instance when the SQLite database file is not present or cannot be accessed.
This error also occurs when the version of the PHP installation on your server is too low (see Requirements above). In this case syntax errors may occur, which are logged in a log file on the server. The location of this log file varies per provider. In this case ask your provider how to upgrade to a higher PHP version.
When logging in your name is not displayed at the right top of the window
When logging in, for instance as administrator, your name should appear in the right upper corner of the window. Sometimes this doesn't happen and after logging in it still reads 'Public View'. This problem occurs when 'sessions' are not enabled, or not working, in the PHP installation on your server. This problem also occurs when cookies are not enabled in your browser.
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 Parameters
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):
lcV: The version number of the LuxCal installation. For example "4.3.0L". 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.
dbType: The type of database used. This can be either MySQL or SQLite.
dbDir: The name of the directory where the calendar database files are stored, relative to the calendar root directory.
dbDef: The default calendar. When multiple calendars are installed and no calendar is specified in the calendar URL, then this default calendar will be opened.
dbSel: This parameter specifies whether, in case of multiple calendars, a calendar selection menu should be present in the calendars Option Panel (for the admin only).
b. Installing Automatic Periodic Functions
The following automatic periodical functions are available:
- Email notification messages for event due dates
- Daily email messages with calendar changes
- Daily export of events in iCalendar format
- Automatic deletion of expired events
- Automatic deletion of expired (unused) user accounts
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. A general description of how to define a cron job can be found in the header of the file 'lcalcron.php' in the calendar root folder.
- 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:
- Download and unzip the desired language pack from the LuxSoft site.
If your language pack is not available:
translate the files lang/ai-english.php and lang/ui-english.php (translate the texts to the right of the => signs) and save the files with the names ai-{newlang}.php and ui-{newlang}.php respectively.
Use character encoding utf-8 without BOM (see note below).translate the file lang/ug-english.php (leave the html tags unchanged) and save it with the name ug-{newlang}.php.
Use character encoding utf-8 without BOM (see note below).
upload the files ai-{newlang}.php, ui-{newlang}.php and ug-{newlang}.php to the lang/ folder on the server.
on the Settings page (see Calendar Configuration Settings in Section 4 below), change the user interface language in the Calendar Settings to the new language.
if the user interface language menu is displayed in the calendar's options panel, the new installed language will automatically be added to the menu.
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:
- SMTP server address
- SMTP port number (often port 25 or, if SSL enabled, 465.
- SSL (Secure Socket Layer) enabled/disabled
- SMTP server user name
- SMTP server password
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:
- SMTP server address: smtp.gmail.com
- SMTP port number: 465
- SSL (Secure Socket Layer): enabled
- SMTP server user name: my.mail
- SMTP server password: mygmailpassword
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 one calendar with its SQLite database will be installed.
There are two ways to add additional calendars:
- Start the installxxx.php script (xxx is the calendar version), which ran automatically during the initial installation, a subsequent time directly via your browser (www.yoursite.xxx/calfolder/installxxx.php). The installation script allows you to install multiple calendars, to change the default calendar and folder and to change the administrator credentials.
- After the initial installation, upload the LuxCal tool lctools.php from the LuxCal toolbox and launch the tool via your browser. Via this tool you can create additional calendars and it offers you various other functions to manage your calendar installtion.
5. Adding the Calendar to an Existing Web Page
To use the calendar on an other web site, the following possibilities are available:
link to the calendar's URL, which will open the calendar in a new page.
Add an Upcoming Events Sidebar. This light-weight list shows all public events for the coming x days.
embed a mini calendar, which can be used to view events and - if enabled by the admin - add, edit and delete events.
embed the full calendar with navigation bar, which the visitor can use to change the options the calendar.
embed one specific calendar view without navigation bar. The visitor cannot navigate to other views and cannot change the options of the calendar
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>
If you want to display a subset of the available events, see "Applying Filters to the Calendar" below.
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}; *
$sbCal = {calendar ID}; *
$sbContent = {sidebar content}; *
$sbHeader = {sidebar title}; *
$sbGroups = {list of user groups for which events to show}; *
$sbCats = {list of event categories to show}; *
$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}; *
$sbWeekDay = {week day for which events to show}; *
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.- <?php: start PHP and ?>: end PHP. If the lines of code are added to a PHP section, these PHP-tags can be omitted.
- $sbClass: This is the class of the container <div>-tag which is used in the CSS to define the style for the sidebar container. This line of code is optional and will default to 'sideBar'. The styles for 'sideBar' are defined in the file css/css_sbar.php of your calendar installation.
- $sbCal: This is the name of the calendar database file (without extension) to be used. If not specified, the default calendar from the lcconfig.php file will be taken.
- $sbContent: This variable defines the content of the sidebar. If its value is 'todo', the sidebar will show the ToDo list, which is a list with events requiring an action. In this case an interactive checkbox is displayed in front of each event which can be checked/unchecked by each visitor. This line of code is optional and when omitted the sidebar content will default to the upcoming events list.
- $sbHeader: The title of the sidebar. This line of code is optional. If not specified, the title of the sidebar will be taken from the language files.
- $sbGroups: This is a list with one or more user group ID numbers (see admin's User Group page) for which events should be included in the sidebar. The ID numbers should be separated by commas. This line of code is optional. If not specified, the events of all user groups will be included.
- $sbCats: This is a list with one or more event category ID numbers (see admin's Categories page) that should be included in the sidebar. Just the value 0 (zero) means 'show all event categories'. The ID numbers should be separated by commas. This line of code is optional. If not specified, all event categories will be included.
- $sbUsersIn: This is a list with one or more user ID numbers that should be included in the sidebar (for user IDs see admin's Users page). The ID numbers should be separated by commas. This line of code is optional. If not specified, the events of all users will be included.
- $sbUsersEx: Same as above, but for users to be excluded (for user IDs see admin's Users page). If $sbUsersIn is specified, $sbUsersEx will be ignored.
- $sbMaxNbr: Maximum number of events to show in the sidebar.
- $sbUpDays: Maximum number of day to show. If not specified, the number of "Days to look ahead in sidebar" from the admin's Settings page will be taken
- $sbWeekDay: The week day for which events should be shown. 1 = Monday, 2 = Tuesday, . . . 7 = Sunday. If specified, the $sbUpDays (see above) will automatically be set to 1. If not specified, events will be shown for all days of the week.
- include: At this place the sidebar code will be included.
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';
$sbCats = '2,4';
include './mycalendarfolder/lcsbar.php';
?>
<?php
$sbClass = 'sideBar2';
$sbHeader = 'All other events';
$sbCats = '1,3,5';
$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>
If you want to display a subset of the available events, see "Applying Filters to the Calendar" below.
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)
If you want to display a subset of the available events, see "Applying Filters to the Calendar" below.
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:
- cP to set the view (e.g. year: cP=1, month: cP=2, . . . , upcoming: cP=7)
- cL to set the user-interface language (e.g. French: cL=Francais). The specified language must be present in the lang/ folder)
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.
If you want to display a subset of the available events, see "Applying Filters to the Calendar" below.
f. Applying Filters to the Calendar
When using a link to the calendar, embed a minicalendar or embed the full calendar, parameters can be added to the calendar URL to specify which events hould be shown. When adding parameters, the following syntax should be used: The first parameter starts with a '?' and parameters are separated by an '&', like: www.mysite.net/calendar?par1=3&par2=7. If a parameter can have several values it can be passed as an array by adding square brackets toe the parameter name, like: www.mysite.net/calendar?par1[]=3&par1[]=7.
Parameter cG can be added to the URL to specify the IDs of one or several user groups for which events should be displayed. Parameter cC can be added to the URL to specify the IDs of one or several event categories for which events should be displayed. The user group IDs and event category IDs can be found on the admin's User Group page and Categories page respectively. For example, to specify a user group, with ID 4 the parameter "?cG[]=4" should be added to the URL. If the events of a second user group, for instance, with ID 6 should be displayed as well, then "?cG[]=4&cG[]=6" should be added to the URL. The same counts for the cC parameter when specifying one or more event categories to show.
Example:
If you want to display a calendar without header (navigation bar) showing events from users in the user groups
with IDs 4 and 7 and only showing events in event category 2, then the link should be like:
www.mysite.net/calendar?hdr=0&cG[]=4&cG[]=4&cC[]=2.
g. 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:
- start PHP sessions, if not done already, by adding the following PHP statement to the parent website
PHP script:
session_start();
PHP sessions must be started before anything is sent out to the browser (like header information), so this statement must be added somewhere at the start of the script. - save the user name or the user email address in the session variable 'lcUser' by adding the following
statement to the parent website PHP script at any point before the iframe statement with the calendar URL:
$_SESSION['lcUser'] = '<user email>';
The part<user email>
is a string with the user email address which corresponds to the email address required to log the user in to the calendar (specified by the admin when the calendar user account was created).
Because PHP session data are stored on the server, the user name / email address are not visible to the users.