Theme Creating
Helios Calendar allows installation of multiple public calendar designs through it's themes support.
Themes contain the PHP, HTML, CSS, JavaScript and Image files that create the public calendar layout and design. In addition to design customization themes can be also modify the functionality of the public calendar by changing default behavior and introducing new functionality through custom hacks.
When building your first theme it is advantageous to use an existing theme to start your customizations. The default theme (/themes/default) included with Helios Calendar includes all of the available public calendar components & functionality and makes an excellent starting point for creating your own custom theme.
To upgrade-proof your theme it must have a unique name. This can be accomplished by renaming the default theme directory to something unique (you can use any name you prefer, however, the new directory name should not include spaces. Additionally, to help identify your theme within the themes settings more easily you can update the comment within the default theme style sheet (/themes/default/css/style.css).
@name YOUR_THEME_NAME
@version 1.0
@author YOUR_NAME
@link YOUR_URL
@description YOUR_THEME_DESCRIPTION - based on Helios Calendar Default Theme
The directory you create for your theme should be located within the /themes directory and named in lowercase. mIxEd CaSe directory names, or CAPITALIZED directory names, are not supported.
The exact files in each theme can vary, however, there is a minimum set of files required to create a complete theme (one that works for every section of the public calendar). These files include:
- archive.php - Public Newsletter Archive
- event.php - Event Details
- form.php - Calendar Forms (Search, Submit Event, Newsletter Sign-Up, etc.)
- index.php - Event Browse
- location.php - Location Profile
- map.php - Location Map
- newsletter.php - Newsletter “Welcome Page”
- series.php - Event Series List
- tools.php - Public Calendar Tools (Can be customized to include additional calendar tools.)
These files should be located within the theme directory:
Ex:
- /themes/<your_theme>/archive.php
- /themes/<your_theme>/event.php
and so on.
In addition to the files listed above many themes contain the following files to compartmentalize content shared across every page. By separating this content into it's own file development, and long-term maintenance, of the theme is easier.
- footer.php
- header.php
- side.php
It is common for themes to contain secondary content (displayed along a the side of the page in a separate column or columns) in their own files. Helios Calendar supports multiple custom named “side files”. These files can be named, and loaded within the theme, using the following structure:
- filename => function call
- side.php => get_side();
- side2.php => get_side('2');
- side_somethingelse.php => get_side('_somethingelse');
and so on. This allows for the construction of multiple shared side files, compartmentalizing secondary content in an easier to manage format.
Note: Side file names should begin with “side” and end with “.php” (without quotes).
- preview.png - Preview thumbnail of the theme used within the admin console Themes Settings. This file is optional but helpful when adjusting theme settings.
As a matter of organization it is recommended that these files be separated into their own directories within the theme, however, as they are referenced directly within the theme they can be located anywhere within the theme directory you prefer.
For example, the default theme uses:
- /default/css
- /default/img
- /default/js
All themes produced by Refresh utilize HTML5 and CSS3 for their markup and style sheets, however, this is optional and can be customized to your preferences. For example, to change the doctype of the default theme you could edit the header.php file and replace:
<!doctype html>
with the doctype of your preference.
Use of event & location images (added to the event/location as a URL within the admin console when managing events/locations) is theme dependent. Not all themes include support for this feature, however, it can be enabled/disabled & customized for each theme depending on publisher preference.
To enable event images within the event browse for your theme edit your theme's index.php file and change the event_browse() function call to pass a value of 1 for the show_images parameter.
Examples:
- Show Images in Event Browse:
<?php event_browse(1);?>
- Disable Images Event Browse:
<?php event_browse(0);?>
The event browse image can be styled using the class eimage_b within the theme style sheet.
To enable event & location images within event details & location profiles you can include the image markup () within your theme pages. This markup can be placed anywhere within the page and styled using CSS within your theme style sheet.
<?php echo '<img src="'.$myEvnt['Image'].'" id="eimage_d" />';?>
The event image can be styled within the event details page by using the ID eimage_d within the theme style sheet.
<?php echo '<img src="'.$myLoc['Image'].'" id="limage_p" />';?>
The location image can be styled within the location profile by using the ID limage_p within the theme style sheet.
Note: The id begins with a lowercase L for locationimage_profile.
Each theme can utilize supported custom theme functions uniquely to individualize public calendar functionality to the needs of each theme.
Once development of your theme is complete you can install your theme by uploading your entire theme directory to your Helios Calendar install. For example, if your theme was named “My Theme” and was stored in a directory named /mytheme you would install your theme directory to your Helios Calendar install at:
/themes/mytheme
Once your theme is uploaded you can activate your theme as an option within the Theme Switcher by purging your cache files. Additionally, you can set your theme as the default by updating your default theme settings.
To test a theme before activating it sign in to the admin console and select it from the available themes, this will allow you to preview the theme on the public calendar without setting it to the default (and making it available to all users).
When applying upgrades reference the list of Deprecated Functions to confirm if any themes or hacks in use on your Helios Calendar utilize functions scheduled for removal. In the event that updates to deprecated functions affect your themes or hacks they should be addressed as quickly as is convenient to ensure long-term compatibility.