Adventcalendar_XH – a CMSimple_XH Plugin

Plugin icon

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's possible to present whatever you like (poetry, images, videos, products etc.)

Please do read this documentation before you encounter any problems!

Important Notice

Adventcalendar_XH couldn't be tested so far in various environments. It is a so called BETA version. Use with caution!

back to top

Requirements

Adventcalendar_XH is a plugin for CMSimple_XH. It requires a UTF-8 encoded version and the jQuery4CMSimple plugin.

back to top

Installation

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

  1. Backup the data on your server.
  2. Unzip the distribution on your computer.
  3. Upload the whole directory adventcalendar/ to your server into CMSimple_XH's plugins directory.
  4. Set write permissions to the subdirectories config/, css/, languages/ and the data folder of the plugin.
  5. Switch to "Adventcalendar" in the back-end to check if all requirements are fulfilled.
back to top

Settings

The plugin's configuration is done as with many other CMSimple_XH plugins in the website's back-end. Select "Adventcalendar" from "Plugins".

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, or customize them according to your needs.

The look of the Adventcalendar_XH can be customized under "Stylesheet".

back to top

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're logged in as administrator you can access all doors for testing purposes.

back to top

Quick Start Guide

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

  1. Browse to "Plugins" → "Adventcalendar" → "Main Settings" and press "Prepare Cover".
  2. Create a new hidden CMSimple_XH page with the heading "winter" (letter case is important) and without content.
  3. Create some hidden subpages of these page with arbitrary headings and content.
  4. Enter the following plugin call on another page: 
    {{{PLUGIN:adventcalendar('winter');}}}
  5. 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.
back to top

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 file has to be "winter.jpg". Then browse to "Plugins" → "Adventcalendar" → "Main Settings", 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 plugin's configuration. The order of the doors is chosen randomly; if you don't like the chosen order, just prepare the image again.

back to top

Prepare the Secrets

Create a new CMSimple page with the name of the advent calendar as heading (the menu level of the page doesn't 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, just redirect the respective sub page to the existing one and append "&print" to the URL.

back to top

Display the Calendar

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

{{{PLUGIN:Adventcalendar('name_of_the_calendar');}}}

Of course "name_of_the_calendar" must be replaced with the actual name of your advent calendar.

back to top

Limitations

back to top

License

Adventcalendar_XH is licensed under GPLv3.

© 2012-2013 Christoph M. Becker

Russian translation © 2012 Любомир Кудрай.

back to top

Credits

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

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

This plugin uses free applications icons from Aha-Soft. Many thanks for making these icons freely available.

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 wouldn't exist.

back to top