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 possible way.
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 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.
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.
The checkbox "Public" can be unchecked to exclude certain event categories from being viewed by the "Public User" and from the RSS feeds.
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 "approved" or "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 Users menu in the navigation bar allows the user(s) with 'manager' rights or 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: "None", "View", "Post Own", "Post All", "Manager" 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 calendar 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 user self-registration on the Settings page, users can register themselves via the Login page. Self-registered users have the access rights specified by the administrator on the Settings page.
Explanation of User Rights:
None
The user - normally the Public User - has no access rights and has to log in to use the calendar.
View
The user can view the calendar, but has has no rights to add or edit events.
Post Own
The user can view the calendar and can add events. The user can only edit his/her own events.
Post All
The user can view the calendar and can add events. The user can edit his/her own events as well as events of other users.
Manager
A user with 'Manager' rights can do the same as a user with 'Post All' rights and in addition:
- Can change the owner of an event (in the Event window). So for instance a manager can create events for other users by creating an event and then assign an owner to it.
- Can approve events created by other users. See Advanced Functions hereafter.
- Have access to the Categories and Users pages and consequently can manage event categories and user accounts.
Administrator
The administrator has all right described above and in addition has access to all technical, user-interface and database related settings.
The Database menu in the navigation bar allows the calendar administrator to start the following functions:
check and repair the database.
This function checks the 'event' table and the 'dates' table of the database on inconsistencies and, when found, repairs the inconsistencies. The number of inconsistencies found is indicated for each table.
Compact database
During normal use of the calendar, when deleting events, the event records are not physically deleted from the database, but are marked as 'deleted'. They can still be used in views and reports; for example in the Changes view. The compact database function permanently removes events from the database which have been marked as 'deleted' more than 30 days ago. Thereafter all tables are compressed to free unused space and to reduce database overhead.
Backup database
This function creates a backup of the structure and contents of all database tables in the files/ directory. The file name is cal-backup-yyyymmdd-hhmmss.sql (where 'yyyymmdd' = year, month, and day, and hhmmss = hour, minutes and seconds). The file type is .sql and the created file can directly be used to re-create the database tables structure and contents, for instance by using the Restore database function (see hereafter) or by importing the file in the phpMyAdmin tool which is available on the server of most web hosts.
Restore database
This function uses the last created backup file in the files/ folder to recreate the calendar database. The database will be recreated from scratch, which means that, before recreating a table, the existing table and its data will be deleted. For each recreated table the corresponding records from the back-up file will be restored to the newly created table.
Back up files of older LuxCal versions can be restored as well, however in this case a warning will be displayed and after the restoration the script upgradxxx.php must be run to upgrade the table structure to the installed LuxCal version.
delete / undelete events
With this function the administrator can delete or undelete all events in a specified date range. Deleted events will be marked 'deleted', but are not yet physically deleted from the database. When the administrator runs the 'compact database' function, described above, events which are physically deleted from the database cannot be undeleted anymore.
When selecting this function and a date in the date range is not specified, the default will be 'unlimited'. This means that if both start and end date are not specified, all events will be (marked as) deleted / undeleted.
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".
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 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".
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, 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.
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.
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 kbd>Views 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 custom free-format 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 'Hover box event fields' under Views, '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 order of the specified numbers determine the order of the displayed fields.
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 calender's navigation bar.
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".
A stand-alone sidebar with upcoming events or a Todo list (see above) can be integrated in your web page. The 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. 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.
When defining user accounts, a background color can be assigned to each user and when defining event categories, a text color and a background color can be assigned to each category. On the admin's Settings page, under Events, the admin can select whether the color of the event titles in the various views should correspond to the color of the user (the originator of the event) or the event category assigned to the event.
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 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:
calendarTitle: The title of the LuxCal calendar that is displayed in the header of the various calendar views.
calendarUrl: The full URL address of the calendar, used for notification purposes, E.g. http://www.mysite.xxx/calendar/index.php.
calendarEmail: The sender's e-mail address ("From") in emails sent by the calendar. E.g. reminders, cron job summary reports. See also notifSender below.
backLinkUrl: URL of parent page. If specified, a Back button will be displayed on the left side of the Navigation Bar which links to this URL. For instance to link back to the parent page from which the calendar was started.
timeZone: Your local time zone. See the PHP Supported Time Zones for possible values. Setting the correct time zone is important for the "today" indication in the various views and when the "notification" feature is used.
notifSender: When the calendar sends reminder emails, the sender field of the email can contain either the calendar email address, or the email address of the user who created the event. In case of the user email address, the receiver can reply to the email.
rssFeed: If enabled: RSS feed links will be displayed in the calendar footer and will be included in the HTML head section.
navButText: If enabled: The buttons on the navigation bar will be displayed with text
navTodoList: If enabled: A Todo list button will be displayed on the navigation bar, which can be used to display the Todo list.
navUpcoList: If enabled: An Upcoming button will be displayed on the navigation bar, which can be used to display the Upcoming Events list.
userMenu: Specifies whether the user filter is displayed in the calendar's options panel. Possible values: 0 = disabled, 1 = enabled.
catMenu: Specifies whether the event category filter is displayed in the calendar's options panel. Possible values: 0 = don't display the category filter menu, 1 = display the category filter menu.
langMenu: Specifies whether the calendar users are allowed to select their preferred user interface language the calendar's options panel. Possible values: 0 = don't display the language selection menu, 1 = display the language selection menu.
defaultView: The initial calendar view to be displayed when the LuxCal Calendar is started. Possible values/views: 1 = Year, 2 = Full Month, 3 = Work Month, 4 = Full Week, 5 = Work Week, 6 = Day (today), 7 = Upcoming events and 8 = Changes.
language: The default user interface language. Only installed languages can be specified.
privEvents: Can be disabled, enabled or default. If enabled: The user can choose to create private events, which are hidden from other users. If default: All events entered by a logged in user will default to private.
details4All: If disabled: event details will only be visible to the owner of the event and to users with 'post all' rights. If enabled: event details will be visible to the owner of the event and to all other users. If "for logged-in users": Event details will only be visible to logged-in users.
evtDelButton: If disabled: the Delete button in the Event window will not be visible. If enabled: the Delete button in the Event window will be visible, so all users with sufficient rights can delete events. If manager: the Delete button in the Event window will only be visible to users with "manager" rights.
eventColor: Specifies whether events should be displayed with the event owner color, or with the event category color (0: owner color, 1: category color)
xField1 / xField2: The name of two optional free format text fields, which can be added to the Event window form and in all calendar views and pages. The specified name can be max. 15 characters long. E.g. 'Email address', 'Website', 'Phone number'.
selfReg: Indicates whether users can register themselves via the Log-in page. Possible values: 0 = self-registration disabled, 1 = self-registration enabled.
selfRegPrivs: The access rights for self-registered users. Possible values: 1 = view, 2 = post self (post events and edit own events), 3 = post all (post events and edit own and other user's events).
selfRegNot: Indicates whether a notification should be sent to the admin when a user has self-registered. Possible values: 0 = disabled, 1 = enabled.
saveLastSel: Indicates whether the last user selections (the Option Panel settings) should be saved. When the user revisits the calendar at a later moment, these values will be restored. Possible values: 0 = not set, 1 = set
cookieExp: Number of days before a 'Remember me' cookie - set during Login - expires
evtTemplGen: Specifies which event fields should be displayed and in which order, on the general calendar views and pages.
evtTemplUpc: Specifies which event fields should be displayed and in which order in the Upcoming Events view.
popBoxYear: Specifies whether a pop up box with event details should be displayed in Year view when hovering an event.
popBoxMonth: Specifies whether a pop up box with event details should be displayed in Month view when hovering an event.
popBoxWkDay: Specifies whether a pop up box with event details should be displayed in Week/Day view when hovering an event.
popBoxUpc: Specifies whether a pop up box with event details should be displayed in Upcoming Events view when hovering an event.
yearStart: The start month in year view (1-12 or 0, 0: current month).
colsToShow: The number of months to show per row in year view.
rowsToShow: The number of 4-months rows to show in year view. The default value is 4.
weeksToShow: The number of weeks to show in month view. The value 0 (zero) has a special meaning and will result in the display of just one single full month. The default value is 10.
workWeekDays: A string of numbers which specify the days of the week to show in work month view and work week view. Valid day numbers are: 1 = Monday, 2 = Tuesday, ... , 7 = Sunday.
lookaheadDays: The number of days to look ahead in upcoming view, todo list and RSS feeds. The default value is 14 (two weeks).
dwStartHour: The start of the full time block on the day and week views. The default value is 6 (corresponding to 6:00am). This parameter helps to avoid wasting space for the nightly hours, where normally no, or very few, events are planned.
dwEndHour: The end of the full time block on the day and week views. The default value is 18 (corresponding to 18.00/6:00pm). This parameter helps to avoid wasting space for the nightly hours, where maybe no, or very few, events are planned.
dwTimeSlot: The time slot size (in minutes) in day/week view. Together with the dwStartHour (see above) this value determines the number of rows in day/week view.
dwTsHeight: The time slot display height (in number of pixels) in day/week view.
eventHBox: Indicates whether an overlay with events details should pop up when the user hovers an event square in Year view or an event title in Month, Week or Day view. Possible values: 0 = disabled, 1 = enabled. The default value is 1.
showLinkInMV: Specifies whether URL-links, specified in the description field or one of the extra fields (see xField1 and xField2 above) of the events, should be shown in month view (0: no, 1: yes)
dateFormat: Text string defining the format of dates in dd, mm and yyyy. Possible characters: y: yyyy, m: mm, d: dd and any non-alphanumeric as separator.
MdFormat: Text string defining the format of dates in dd and month. Possible characters: d: dd, M: month in letters and any non-alphanumeric as separator.
MdyFormat: Text string defining the format of dates in dd, month and yyyy. Possible characters: d: dd, M: month in letters, y: yyyy and any non-alphanumeric as separator.
MyFormat: Text string defining the format of dates in month and yyyy. Possible characters: M: month in letters, y: yyyy and any non-alphanumeric as separator.
DMdFormat: Text string defining the format of dates in weekday, dd and month. Possible characters: WD: weekday in text, d: dd, M: month in letters and any non-alphanumeric as separator.
DMdyFormat: Text string defining the format of dates in weekday, dd, month and yyyy. Possible characters: WD: weekday in text, d: dd, M: month in letters, y: yyyy and any non-alphanumeric as separator.
timeFormat: Text string defining the format of times in hh and mm. Possible characters: h: hours, m: minutes, a: am/pm (optional), A: AM/PM (optional) and any non-alphanumeric as separator.
weekStart: The first day of the week. Possible values: 0 = Sunday, 1 = Monday.
weekNumber: Specifies whether week numbers should be displayed in the various calendar views. Possible values: 0 = disabled, 1 = enabled. The default value is 1.
mailServer: Specifies whether PHP mail or SMTP mail should be used for email reminders and periodic reports. Possible values: 0 = mail disabled, 1 = PHP mail, 2 = SMTP mail. The default value is 1.
smtpServer: Text string specifying the name of the SMTP server. For gmail this is for instance 'smtp.gmail.com'.
smtpPort: Specifies the SMTP port number. For example 25, 465, 587. Gmail for example uses port number 465.
smtpSsl: Specifies whether Secure Sockets Layer (SSL) should be used. Possible values: 0 = no, 1 = yes. Gmail for instance uses SSL. The default value is 1.
smtpAuth: Specifies whether authentication should be used when sending SMTP mail. Possible values: 0 = no, 1 = yes. Gmail for instance uses authentication. The default value is 1.
smtpUser: Text string specifying the SMTP user name. Required when SMTP authentication should be used.
smtpPass: Text string specifying the SMTP password. Required when SMTP authentication should be used.
adminCronSum: Specifies whether the calendar administrator will receive a summary report after the periodic functions have been executed. Automatic periodic functions should be installed (see below) and emailing cron job output should be enabled on the server.
chgEmailList: A list with destination email addresses for calendar changes sent by the sendchg.php script. Automatic periodic functions should be installed (see below).
chgNofDays: The number of days the sendchg.php script (see previous variable) should look back for calendar changes. If the automatic periodic functions have been installed (see below), this variable could be set to 1 (one day)
icsExport: Export events in iCalendar format to a .ics file in the 'files' folder. The file name is the calendar name with blanks replaced by a underscore. This function works via a cron job.
eventExp: The number of days after the event's due date when an event expires and will be automatically deleted (0:never). This function works via a cron job.
maxNoLogin: Indicates after how many 'no-login' days a user account should be automatically deleted. Possible values: 0 = never delete a user account, 1 - 365 = number of days. Automatic periodic functions should be installed (see below).
miniCalView: The calendar view for the LuxCal mini calendar. Possible values/views: 1 = Full Month, 2 = Work Month, 3 = Full Week, 4 = Work Week.
miniCalPost: Indicates whether events can be added, edited and deleted via the mini calendar without opening the full calendar. Possible values: 0 = posting of events disabled, 1 = posting of events enabled. The default value is 0.
popFieldsMcal: Specifies which event fields should be displayed in the hover box with event details in the mini calendar. Only fields which are also defined in the setting "evtTemplate" will be displayed. If no fields are specified, no hover box will be displayed.
mCalUrlFull: When clicking the month at the top of the mini calendar, to go to the full calendar, the user will be directed to this URL. If not specified, the full calendar will open in a new window. This URL is in particular useful when the full calendar is embedded in an existing user page.
popFieldsSbar: Specifies which event fields should be displayed in the hover box with event details in the stand-alone sidebar. Only fields which are also defined in the setting "evtTemplate" will be displayed. If no fields are specified, no hover box will be displayed.
showLinkInSB: Specifies whether URL-links, from the description field of the events, should be shown in the sidebar (0: no, 1: yes).
sideBarDays: The number of days to look ahead in the sidebar. The default value is 14 (two weeks).