a LuxSoft product

LuxCal Event calendar

 

Administrator's Guide

Table of Content

  1. Introduction

  2. Managing the Calendar

    1. Calendar Settings

    2. Event Categories

    3. Calendar User Groups

    4. Calendar Users

    5. Calendar Database

    6. CSV File Import

    7. iCal File Import/Export

  3. Advanced Functions

    1. Changing the Lay-out of Events

    2. Event Check Mark and To Do List

    3. Proposing / Approving Events

    4. Private Events

    5. Using the Calendar to Book Events

    6. Sidebar with Upcoming Events or Todo List

    7. Color-coding of Events

    8. Importing Data of Previous LuxCal Versions

  4. LuxCal Toolbox

    1. General Toolbox - lctools.php

    2. PHP Installation Details - phpinfo.php

    3. SMTP Mail Test Utility - smtptest.php

    4. LDAP integration (experimental)

    5. Database administration with phpLiteAdmin

  5. Calendar Settings - Description


1. Introduction

After the LuxCal calendar has been installed or upgraded, using the installation_guide.html, this Administrator's Guide is meant to help the calendar administrator to set up the more advanced functions of the LuxCal calendar and to maintain the calendar so that it's functionality meets the needs of the users in the best suitable way.

A good place to start in managing your calendar is to . . .

To familiarize yourself with the LuxCal calendar's capabilities, it is important to take notice of the other function and possibilities described in this section.

2. Managing the Calendar

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

Managing event categories, user profiles and user groups can be done by either the calendar administrator, or users with 'manager' rights.

In order to change configuration settings, or use other administration functions, 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 the password you specified during the installation, and log in. On the right side of the navigation bar the administration drop down menu will appear.

a. Calendar Settings

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, 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 Time Zones for possible values.

b. Event Categories

It is recommended 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 administration 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.

If the "No overlap allowed" check box is checked, events within this category may not overlap. If a user tries to create an event in this category which overlaps with an existing event, an error message with the specified error text will be displayed. This feature can be used when you want to use this event category for booking events. For details on how to create a booking calendar, see Advanced Functions hereafter.

With the field "Default time slot" you can specify the default duration of an event in case the user specifies a start time without an end time. This can be useful for instance when using this category for "booking" events which may not overlap (see above).

When the checkbox "Day color" has been checked, the full day cell in the calendar views will get the background color specified below. This may be useful to clearly mark for example holidays, birthdays, or other special days.

When activated, the field "Event needs approval" will activate the propose/approve feature for events in this category. For a detailed description, see "Proposing / Approving Events" in section 3 below.

A check mark can be activated which will be displayed in front of the event title for all events in this category. The user can use this check mark to flag events, for example, as "completed". Events in this category will appear in the ToDo list, which can be opened from the calendars navigation bar.

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

The field "Sequence" defines the location of this event category in the category drop-down menus.

c. Calendar User Groups

The initial installation has a User Group defined for each possible type of user permission. Each calendar user is assigned to one of the existing user groups. User groups can be edited, and new user groups can be added, by users with administrator or manager rights. Adding and editing user groups is done via the Administration drop-down menu in the navigation bar. A user group defines the user access rights of the users assigned to this group and the event categories available to the users in the group. Furthermore a number of check boxes are available to specify whether users in this group may enter repeating events, multi-day events and private events. Via a color palette a background color can be selected for each group. On the admin's Settings page the administrator can specify whether calendar events should be displayed with the color of the event category or the color of the group to which the creator of the event belongs.

Possible access rights:

d. Calendar Users

Via the Administration drop-down menu user(s) with manager rights or the calendar administrator can add and edit user profiles. Per user the name, e-mail address, password and the user group can be specified. As described above, the group determines the access rights and the available event categories. It is important to specify a valid email address for the user to be able to receive email notifications of due dates of events. When defined users log in to the calendar they can specify their default user interface language. Thereafter, when a user logs in, the user-interface will be displayed in the specified language.

The initial installation has two users defined. One is the Public Access user, who initially is assigned to the "Read access" user group and the other is the calendar administrator, who is assigned to the "Admin" user group and has all access rights.

Unless the calendar administrator has given "View" access (via the "Read access" user group) to Public Access users, users must log in to use the calendar using their name or email address and password. Depending on the group to which a user has been assigned, a user can have different access rights.

If the administrator has enabled user self-registration on the Settings page, users can register themselves via the Login page. Self-registered users will automatically be assigned to the user group for self registered users specified by the administrator on the admin's Settings page and consequently will have the access rights specified for that user group.

e. Calendar Database

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

f. 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 administration 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".

g. 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 administration 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 iCalendar format on the internet. Please note that some LuxCal event fields are not supported in the iCalendar 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".

3. Advanced Functions

The normal day-to-day use of the calendar is explained in the help file which can be viewed by selecting 'Help' (or the question mark) on the right side of the calendar's navigation bar. There are however a number of more advanced functions which can be enabled / configured by users with manager rights or by the calendar administrator.

These advanced functions are described hereafter.

a. Changing the Lay-out of Events

On the Settings page, the admin can specify which fields of the event body are in use and in which order they will be displayed in the various views. This can be done via the 'Event template' under Events by specifying a sequence of numbers in the range 1 - 7, where each number represents an event field.

Possible fields in the event body:

Fields (numbers) which are not specified, will not be visible in the calendar views. Extra fields 1 and 2 are extra fields for which the admin can specify a dedicated label on the same Settings page under Events. If the these fields have been specified, the field label as well as the content will be displayed. In the calendar views active fields which are empty will not be shown. The Event window will of course always show all active fields, including the empty fields.

Example: Event template "43126", with the label for Extra field 1 set to "Department", will for instance result in the following event body lay-out (explanation between brackets):

 Department: Sales (extra field 1 with label "Department")
 Emmett Brown will be working on-site for the BTTF project. (description)
 Venue: Hill Valley (venue)
 Category: Absent (event category)
 (Notify: 4 day(s)) (This line is not displayed, because no email notification was requested)

On the Settings page, the fields 'Event fields - general hover box' under Events, 'Event fields - mini calendar hover box' under Mini Calendar and 'Event fields - sidebar hover box' under Stand-Alone Sidebar can be used by the admin to specify the event fields to be displayed in the various hover boxes. The sequence of the fields in the hover boxes depend on the event template described before.

b. Event Check Mark and To Do List

On the admin's Categories page, when adding/editing an event category, if you select "Check mark" and specify a label and a check mark, events in this category will have a check mark displayed just in front of the event title in the various views. For the owner of the event and users with "manager" rights this check mark is a hyperlink and, when clicked, will open a window to check/uncheck the check mark. This feature can be used for instance to mark an event as "complete" or "done". Events with a check mark will show up in the To Do list, which - when enabled by the administrator - can be selected from the calendar's navigation bar.

c. Proposing / Approving Events

On the admin's Categories page, when adding/editing an event category, if you select "Events need approval", users with post rights can - in this category - create events which are not visible to other users until a user with at least "manager" rights has approved the event. Until the event has been approved, no other user will see the event and both the originator and users with manager rights will see the proposed event in the various views displayed with a red bar on the left side. Once a user with "manager" rights has approved the event, the event will become visible to all users and the event will be locked and cannot be edited anymore by the originator. A user with at least manager rights can still edit the event. Of course, if you don't like the words "proposing" and "approving", you could for example also consider the words "booking" and "confirming".

d. Private Events

When adding/editing events, if the "Private" check box is checked, the event will only be visible to the user who created the event and to the administrator. For obvious reasons private events can only be created by logged in users.

On the Settings page, under Events, the administrator can set "posting of private events to disabled, enabled, default and always with the following meaning:

The creation of private events can also be enabled/disabled per individual user group (see Calendar User Groups above). If for a calendar user group private events have been disabled, this will overrule the "Posting of private events = always" setting on the admin's Settings page.

e. Using the Calendar to Book Events

One or several event categories of the calendar can be set up for booking events with event overlap checking. The idea is to let users create events which may not overlap with already existing events in the same event category. If a user tries to create an event which overlaps, an error message will be displayed. Single-day and multi-day events are checked. Recurring events and private events are not checked.

How to set up a booking system, is illustrated by the following example.

Billiard table booking example:

In this example we will set up a booking system for three billiard tables.

Create a new event category and give it the name "Billiard table 1", uncheck the "No overlap allowed" check box, and optionally set the error text, displayed in case of creating an event which overlaps with an existing event, to "Billiard table 1 in use, choose an other time or table". If desired, the "Default time slot" can be specified, which - when creating / editing an event - will automatically be added to the start time of an event if no end time is specifies. Give this category a color (text/background) which belongs to table 1.
Create two more categories for the other two billiard tables in a similar way but with a different name, error text and color.
Now a user group can be created, for instance with the name "Billiards" for those users who can book one of the three billiard tables. For this user group the three categories created for the billiard tables should be selected and the check boxes "May post repeating events" and "May post private events" should be unchecked. Because the billiard tables can only be booked for a limited time, the check box "May post multi-day events" can also be unchecked. So now if a user in this group add/edits an event, the Event window will be simplified and will contain no "Private" check box, no "End date" field and no "Repeat" feature.
On the Settings page, under User Accounts, "Self registration" can be enabled and the "Self registration user group" should be set to the user group "Billiards" created in the step above.

In the above example, users can register themselves and will be part of the "billiard" user group; they will have access to the three categories "Billiard table 1", "Billiard table 2" and "Billiard table 3" and will only be able to book a billiard table which is free.

Note: For a booking system for chalets for instance, in the user group the check box "May post multi-day events" should remain checked, to allow for booking the chalets for several days.

f. Sidebar with Upcoming Events or Todo List

A stand-alone sidebar with upcoming events or a Todo list (see above) can be integrated in your web page. An advantage of the sidebar, compared to embedding the calendar in an html iframe, is that the sidebar is displayed in a <div> container and can be freely styled to match the style of your web page. A second advantage is that the hoverbox with many event details is not clipped by iframe boundaries. Further detail on how to add one or more stand-alone sidebars to your web page can be found in the installation_guide.html. Examples of what a sidebar can look like can be found on the LuxSoft Demo page.

g. Color-coding Events

When defining user groups, for each group a background color can be specified and when defining event categories, a text color and a background color can be specified for each category. On the admin's Settings page, under Events, the admin can select whether on the calendar pages the color of the event titles in the various views should correspond to the color of the user group to which the originator of the event belongs or to the event category to which the event belongs.

When adding/editing event categories a check box "Day color" can be checked. If this check box is checked, in the various calendar views, if an event in this category is displayed for a certain day, the background of the whole day will take the color of the event. This can for instance be useful to make special events, like holidays or birthdays, more visible.

h. Importing Data of Previous LuxCal Versions

There are different ways to import calendar data of previous LuxCal versions, back to LuxCal version 2.7.2. If you want to import data of a LuxCal version less than 2.7.2, read the Upgrade Instructions in the Release Notes (release_notes_xxx.html, where xxx = the LuxCal version).

When in doubt if the calendar data in your database is up to date, you can at any time upload the upgradexxx.php file to the calendar root folder on your server and launch it. The script will verify, and if necessary upgrade, the database schema of your calendar(s).

4. LuxCal Toolbox

The toolbox contains several tools and utilities, which can help you set up and manage your calendar. Below you will find a short description of each of the tools / utilities.

4a. General Toolbox - lctools.php

The lctool.php file should be uploaded to the calendar's root directory and launched via your browser. This toolbox is particularly useful when managing multiple calendars. It contains tools to perform the following actions:

Most actions should be used with caution. Always carefully read the displayed instruction!

4b. PHP Installation Details - phpinfo.php

The phpinfo.php utility should be uploaded to the calendar's root directory on your server and should be launched via your browser. When started, this utility will display all installation details of the PHP installation on your server.

4c. SMTP Mail Test Utility - smtptest.php

When you prefer to use SMTP mail, rather than PHP mail, for your email reminders and cron job reports, you can select SMTP mail on the admin's Settings page of your calendar. Before doing so you can use the SMTP Mail Test Utility "smtptest.php", in the smtpmail folder, to test your SMTP mail and its parameters. The smtptest.php file should be uploaded to the calendar's root directory on your server. Before launching it via your browser, you should start the calendar and specify the SMTP parameters on the admin's Settings page, under Email Settings.

4d. LDAP Integration (Experimental)

In the ldapmod folder you will find instructions and files to implement LDAP (Lightweight Directory Access Protocol) integration for the LuxCal calendar. A common usage of LDAP is to provide a "single sign on" where one password for a user is shared between various services on an intranet.

The LDAP Integration module has been produced by Martin Dziobek, HLRS Uni Stuttgart. For further details see the README.txt file in the ldapmod folder in the LuxCal toolbox.

4e. Database Administration with phpLiteAdmin

In the phpliteadmin folder you will find phpLiteAdmin, an easy to use web-based SQLite database admin tool written in PHP. details on how to use this free tool can be found here.

In the associated phpliteadmin.config.php file, you should at least set the following variables:

5. Calendar Settings - Description

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 by the calendar administrator via the Settings page in the administration 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:


 - End of Administrator's Guide -

design 2016 - powered by LuxSoft