Adventcalendar_XH

Adventcalendar_XH facilitates to display an advent calendar on your site. The little doors can only be opened by visitors up to the current date. The secrets behind the doors are the contents of CMSimple_XH pages, so it is possible to present whatever you like (poetry, images, videos, products etc.)

Requirements
Download
Installation
Settings
Usage
Limitations
Troubleshooting
License
Credits

Requirements

Adventcalendar_XH is a plugin for CMSimple_XH. It requires CMSimple_XH ≥ 1.7.0, and PHP ≥ 7.1.0 with the gd Extension.

Download

The lastest release is available for download on Github.

Installation

The installation is done as with many other CMSimple_XH plugins. See the CMSimple_XH Wiki for further details.

Backup the data on your server.
Unzip the distribution on your computer.
Upload the whole folder adventcalendar/ to your server into the plugins/ folder of CMSimple_XH.
Set write permissions for the subfolders config/, css/, languages/ and the data folder of the plugin.
Navigate to Plugins → Adventcalendar in the back-end to check if all requirements are fulfilled.

Settings

The configuration of the plugin is done as with many other CMSimple_XH plugins in the back-end of the Website. Select Plugins → Adventcalendar.

You can change the default settings of Adventcalendar_XH under Config. Hints for the options will be displayed when hovering over the help icons with your mouse.

Localization is done under Language. You can translate the character strings to your own language, if there is no appropriate language file available, or customize them according to your needs.

The look of the Adventcalendar_XH can be customized under Stylesheet.

Usage

You can have as much separate advent calendars in a CMSimple_XH installation as you like. These are distinguished by a name. The name may contain alphanumeric characters only and it should not be the same as the heading of any already existing page.

Visitors of your site will not be able to open doors of future days, according to the configuration option Date → Start. When you are logged in as administrator you can access all doors for testing purposes.

Quickstart Guide

To quickly set up a working demo, just follow these steps:

Navigate to Plugins → Adventcalendar → Administration, select the cover image winter, and press Prepare Cover.
Create a new hidden CMSimple_XH page with the heading winter (letter case is important) and without content.
Create some hidden subpages of this page with arbitrary headings and content.
Enter the following plugin call on another page:
```
{{{adventcalendar('winter')}}}
```
Switch to view mode and enjoy the advent calendar. Note, that you can only open as much doors, as you have created subpages of the calendar page.

Prepare the Cover

Find an appropriate background image for your advent calendar, resize it to the desired size (typically the width of the contents area of your template) and upload it to the configured data folder of the plugin. The uploaded image has to be in JPEG format and has to be named like the calendar; so for the calendar winter the filename has to be winter.jpg. Then browse to Plugins → Adventcalendar → Administration, where you can prepare the image to be the cover of your advent calendar. Pressing Prepare Cover will draw the little doors with the according day numbers. For images in landscape format there will be 4 rows with 6 doors each; for images in portrait format there will be 6 rows with 4 doors each. The size of the doors and the colors can be customized in the configuration of the plugin. The order of the doors is chosen randomly; if you do not like the chosen order, just prepare the image again.

Prepare the Secrets

Create a new CMSimple_XH page with the name of the advent calendar as heading (the menu level of the page does not matter). Create a sub page for each day (the 1st sub page is for day 1, the 2nd for day 2 etc.) You can fill the pages with any contents you like, even plugin calls are possible. Typically you will want to hide all these pages from the menu. If you want to use an already existing page as secret behind a door, redirect the respective sub page to the existing one and append &print to the URL.

Display the Calendar

Display the advent calendar on any CMSimple_XH page by calling the plugin:

{{{adventcalendar('%CALENDAR_NAME%')}}}

%CALENDAR_NAME% must be replaced with the actual name of your advent calendar.

Limitations

The lightbox requires a contemporary browser; on old browsers, the contents of the secret pages will be shown as separate page.

Troubleshooting

Report bugs and ask for support either on Github or in the CMSimple_XH Forum.

License

Adventcalendar_XH is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Adventcalendar_XH is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantibility or fitness for a particular purpose. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Adventcalendar_XH. If not, see https://www.gnu.org/licenses/.

Credits

Adventcalendar_XH uses Colorbox. Many thanks to Jack Moore for publishing this fine lightbox clone under MIT license.

The plugin logo is designed by Enhanced Labs Design Studio. Many thanks for publishing this icon under a liberal license.

Many thanks to the community at the CMSimple_XH Forum for tips, suggestions and testing. Especially I want to thank Korvell for pushing 1beta5 just in time before December 2013.

And last but not least many thanks to Peter Harteg, the “father” of CMSimple, and all developers of CMSimple_XH without whom this amazing CMS would not exist.

cmb69 / adventcalendar_xh