Table of Content
1. Introduction
LuxCal displays are single-file programs meant to create a dedicated events listing of the upcoming events in your calendar. Displays work out-of-the-box and are highly configurable in an easy way. They must be located in the root folder of the LuxCal calendar. Directly after installing or upgrading the calendar you can browse with your browser to the file and see the result. An example of the URL for for instance display1: www.yoursite.xxx/calendar/display1.php.
There are currently 4 different displays available:
- display 0: A mini-calendar showing exactly one month
- display 1 and 2: Event listing of the upcoming events, meant to be embedded in in a web page (via an iframe)
- display 3: Event listing of the upcoming events, meant to be viewed on a narrow width display, like a smart phone in portrait position.
IMPORTANT: To avoid losing your changes when upgrading the calendar, tailoring the configuration settings of displays should NOT be done in the displayX.php files in the calendar root, but should be done as described in section 4 hereafter.
2. Specialties of display 0
- This display shows one calendar month; events are represented by mini-squares or symbols (if defined in the event categories), which cn be hovered to show the event details
- Visitors can skip to next/previous month.
- Visitors can open the full-size calendar by clicking the month+year button in the mini-calendar's header.
- If in the calendar public users have been given post rights, users can add events by clicking in a day cell and can edit an event by clicking on the event symbol.
- If Extra Field 2 contains a URL, clicking on the event symbol will open this URL in a new window.
- Depending on the selected month, the number of displayed weeks can vary. The height of the mini calendar will automatically be adjusted.
- Since the mini calendar will normally be embedded in an iframe, the hover box with event details cannot pass the iframe borders.
3. Specialties of display 1 - 3
- Events can be filtered on various criteria (event categories, event owner user IDs, event owner user group IDs, text in venue field).
- The event head and body are highly configurable.
- Optionally users can log in. When logged in, the settings of the group to which the user belongs apply.
- Images in extra field 1 are floated left and images in extra field 2 are floated right. If in the same extra fields 1 or 2 a URL is found, then the corresponding image will become a hyper-link to this URL. Note: This only works if Extra Field 1 (4) and Extra Field 2 (5) are not present in the in the $evtBody setting.
- If in the full calendar public users or logged in users have been given post rights, they can add events by clicking a date and can edit an event by clicking its title.
- Optionally a PDF button to download a PDF file with upcoming events can be added to the display header (not in display3).
- Display3 has been specially designed for narrow displays, like smart phones in portrait position.
4. Tailoring the display's configuration settings
Displays have a section with default configuration settings, specifying for example which events should be shown and defining the graphical user interface (lay-out, colors, fonts, etc.). The most important configuration settings are explanation at the end of this document.
You can change the default configuration settings in the following ways:
- by copying one of the display .cnf files from the "samples" folder to the 'configs' folder and tailor the settings in this file. Thereafter in the link to the displayX.php file add the parameter "cnf" with the configuration file name (without extension). Example: src="display1.php?cnf=display1a".
- If in the link the cnf parameter is omitted, the display will look for a file with the same name as the displayX.php file and with extension .cnf. Example: "display1.cnf". If present, the display will take the configuration settings from this file.
- If in its turn this file is not present, the display will be shown with its default configuration.
So if you are using only one displayX.php, then copying the configuration file, with the same name as the displayX.php and extension .cnf, from the "samples" folder to the "configs" folder and editing the settings will do.
If you are using multiple displays of the same type (e.g. a display 1 with birthdays and a display 1 (the same) with all other events, then you can copy a configuration file for this display from the "samples" folder to the "configs" folder and make a tailored copy for each of your multiple displays.
5. How to embed displays in your web page
Displays have been designed to be shown in a limited space, they are best viewed on a narrow-width display (for instance a smart phone) or in a narrow-width iframe integrated in your website.
Example:
Integrated in your web page:
<iframe class="display" src="calendar/display1.php"></iframe>In your style sheet:
iframe.display {width:450px;
height:550px;
overflow:hidden;
border:1px solid grey;
border-radius:5px;
box-shadow:5px 5px 5px #888;
}
Optionally displays can be called with a URL parameter ?cats=comma-separated-category-ID-list. In this case only events in the specified categories will be shown, provided that the specified category is part of the category ID list in the display configuration. In this way you can have the same display multiple times in your web pages, each showing events in different categories.
6. Explanation of the general configuration settings used by most displays
Set Start and End Date
- $fromDate and $tillDate
Possible values: A fixed date (yyyy-mm-dd), or one of the keywords DAY, WEEK, MONTH, YEAR, optionally followed by an offset
Examples $fromDate: "2018-01-28" | "DAY-2": today - 2 days | "WEEK": start of this week | "MONTH+1": start of next month | "YEAR": start of this year
Examples $tillDate: "2018-06-14" | "DAY+2": today + 2 days | "MONTH": end of this month | "MONTH+1": end of next month | "YEAR": end of this year
default: $fromDate = "DAY";
default: $tillDate = "MONTH+1";
General Settings
- $calID = "";
Calendar ID. If there are multiple calendars in use, here you can specify which calendar to use. E.g. "mycal". When this setting is left blank (""), the calendar currently in use will be taken. - $calName = "*";
Header text of the display. E.g. "Upcoming events". If an asterisk ("*") is specified, the calendar title will be the header text. When left blank (""), no header will be displayed. - $login = 1;
Show user name and login button in right upper corner. When set to 0, visitors will not be able to log in and events will be shown according to the settings in the user group of the Public Access user. When set to 1, a login button will be shown at the right upper corner. A not (yet) logged in user will see events according to the settings in the user group of the Public Access user. A logged in user will see events according to the settings in his/her user group. If $login = 1 and the public user has no rights, the display will open directly with the login form. When a user logs in, he will automatically be remembered during the number of days specified on the Settings page of the calendar, under 'User Accounts'. - $logMsg = "No account yet? Contact the calendar administrator";
Message shown at the top of the log in page. Only relevant if $login = 1. - $pdfBut = 1;
Show PDF file download button in right upper corner (0: no, 1: yes). - $pdfCnf = "pdf1";
Name of configuration file, without extension, for the creation of the PDF file when the PDF button is clicked; blank (""): use default. - $sortD = 0;
Event sorting on dates; 0: ascending, 1: descending. - $maxDays = 0;
Max. number of days to show; 0: no maximum. - $futEvts = 0;
Show ongoing and future events only (0: no, 1: yes). Note: This setting overrules the "from date" and sets it to "DAY". As soon as the date and end time of an event have not passed the event will not be shown anymore. - $evtHead = '#t #c#/owner: #o';
Event head template. The combination of the # and the subsequent character will be replaced by the corresponding value, as follows: #t: times, #e: event title, #c: event title - category color, #u: event title - owner group color, #o: event owner, #a: age (see note below) #/: new line. All other characters in the template will be part of the event head.
The #a key will be replaced by the age of the person if the following conditions are met: For the category of the event the Repeat field is set to "every year" and somewhere in the event's description field the year of birth in parentheses is present in the format 'yyyy'. E.g. (1989), (2001).
For #a (age) the | character can be used to create an age section; if within this section the #a-parameter results in an empty string, the whole section will be omitted. For instance "|Age: #a|". - $evtBody = '12345';
List of event fields to show. Each number represents an event field, as follows: 1: venue, 2: category, 3: description, 4: Extra field 1, 5: Extra field 2, 6: Email notification data (if requested), 7: Date/time added edited, 8: Attached pdf, image or video files as hyperlink). The order of the events fields corresponds to the order of the numbers. - $evtWin = 1;
On click open event window (0: no, 1: yes). Explanation: If "yes" and the user has no post rights, when clicking an event title the event report window with all event details will open. If "yes" and the user has post rights, when clicking an event title the Edit Event window will open and when clicking a date an Add Event window will open for that date and when clicking the calendar title an Add Event window will open with a blank date. So in this case the visitor can edit and add events, in accordance with the visitor's group settings. - $recOnce = 0;
For recurring events, show only one (the next) occurrence (0: all, 1: next only). - $mulOnce = 0;
For multi-day events, show only one (the next) occurrence (0: all, 1: next only). - $maxImgH = 80;
Maximum height of images (in pixels). - $noEvents = "No events";
Message shown when there are no upcoming events to show.