The structure of Calendar Themes was inspired by the structure of WordPress Themes. If you are already familiar with writing WordPress Themes, then writing Calendar Themes should be easy to pick up. Calendar themes are stored under [wp-root]/wp-content/themes-ai1ec.

The minimum files required for to build a calendar theme can be found in Gamma, the “skeleton” theme we supply with the plugin. Gamma, like all custom calendar themes, is a child theme of Vortex. Vortex is the foundation of all calendar themes, as it provides all the base CSS, images, theme option definitions and template files required for the calendar to function.

To build a new theme, simply duplicate the contents of the gamma theme directory, and then add your customizations. Here’s a summary of what Gamma contains:

In addition to the above required files, themes can provide custom CSS (or LESS) stylesheet files and even custom template files to give your theme its unique look and feel, as explained below.

CSS/LESS

The All-in-One Event Calendar supports both the traditional CSS stylesheet rule syntax, as well as the advanced and much more powerful LESS stylesheet rule syntax. We encourage you to learn the syntax of LESS stylesheets to take advantage of the dynamic stylesheet variables provided by the plugin’s Theme Options pane, not to mention Bootstrap mixins and the many other benefits of using LESS.

The All-in-One Event Calendar processes theme stylesheet files and generates a compiled version that it makes available to all pages of the WordPress front-end (and has a URL of the form [wp-home]?ai1ec_render_css=...).

As a theme developer, all you need to know is where to place your custom CSS or LESS rules. The theme engine looks for an “overrides” stylesheet file, in this order, and picks only the first one that it finds:

1. [your theme]/css/override.css
2. [your theme]/css/override.less.

It appends the rules that it finds in that file after all the default CSS rules from the Vortex theme.

To add custom stylesheet rules to your theme, create either the override.css or override.less file (at your discretion) in the corresponding subdirectory under your theme’s directory, and the rules contained therein will be applied after the default CSS rules.

Which CSS/LESS rules to override?

If you wish to change the appearance of any element in the calendar using a stylesheet rule, the best way to find out what the rule is to use your web browser’s CSS inspector to inspect the element’s applied CSS rules. Document inspectors are available in all modern web browsers (Chrome, Safari, Firefox, and even Internet Explorer – however Internet Explorer’s is more difficult to use). We encourage you to learn how to use your browser’s CSS inspector, as it is the way even our most advanced UI developers determine how CSS is affecting the page, and how to make the page elements display differently.

The recommended procedure is:

1. Inspect the element using your browser’s CSS inspector (often by right-clicking the element and selecting Inspect Element).
2. In the inspector’s list of CSS rules applied to that element, locate the rule blocks that are coming from the All-in-One Event Calendar plugin. These are generally recognizable by the prefix “ai1ec” or “timely” within their rule definition.
3. Optional. If you’re not certain exactly which CSS attributes to change or how to change them, try editing the attributes applied by our plugin live using the CSS inspector. This is often just a matter of clicking or double-clicking an attribute’s value and changing it, or adding a new value to the end of a rule block, and seeing what effect it has on the page.
4. Once you know the attribute(s) you would like to add or modify, create a new rule definition in your override.css or override.less file based on the existing rule definition. For example, say you want to change the way box-shadows are applied to event stubs in Week view. You’ll find that the relevant rule block looks like this:

   .ai1ec-week-view .ai1ec-week a.ai1ec-event-container,
   .ai1ec-oneday-view .ai1ec-oneday a.ai1ec-event-container {
     ...
     -webkit-box-shadow: 1px 2px 4px rgba(0, 0, 0, 0.15);
     -moz-box-shadow: 1px 2px 4px rgba(0,0,0,0.15);
     box-shadow: 1px 2px 4px rgba(0, 0, 0, 0.15);
     ...
   }

   Notice how the same rule is applied to events in Week view (.ai1ec-week) and in Day view (.ai1ec-oneday). It’s important to copy the rule block definition verbatim so that other applications of your rule (in this case, Day view) are included in your change. So to apply your own box-shadow attributes, place this in override.css:

   .ai1ec-week-view .ai1ec-week a.ai1ec-event-container,
   .ai1ec-oneday-view .ai1ec-oneday a.ai1ec-event-container {
     -webkit-box-shadow: 1px 1px 2px rgba(0, 0, 0, 0.3);
     -moz-box-shadow: 1px 1px 2px rgba(0, 0, 0, 0.3);
     box-shadow: 1px 1px 2px rgba(0, 0, 0, 0.3);
   }

5. After you have made any changes to your override.css or override.less file, click Save Options on the Events > Theme Options admin screen to activate your change in the front-end.

LESS variables and Theme Options

As of All-in-One Event Calendar version 1.9, calendar themes can provide customizable colour and font options (and more option types will be supported in version 2.0). A calendar theme defines which Theme Options are available in a file called less/user_variables.php. Each theme option defined in this file maps to a single LESS variable that is used in the theme’s LESS stylesheets.

The base calendar theme, Vortex, defines dozens of theme options in its user_variables.php file. Like other calendar theme files, child themes inherit the parent theme’s (Vortex’s) variable definition file if it does not define one itself. If it does define one, its file is read instead of Vortex’s.

Let’s look at an example of some variable definitions in Vortex’s user_variables.php file:

$less_user_variables = array(

  …

  "linkColor" => array(
    "value"  => "#507295",
    "description" => __( "Link", AI1EC_PLUGIN_NAME ),
    "tab" => "general",
    "type" => "color",
  ),
  "linkColorHover" => array(
    "value"  => "#354c63",
    "description" => __( "Link (hover)", AI1EC_PLUGIN_NAME ),
    "tab" => "general",
    "type" => "color",
  ),
  "baseFontFamily" => array(
    "value"  => "\"Helvetica Neue\", Helvetica, Arial, sans-serif",
    "description" => __( "Base font", AI1EC_PLUGIN_NAME ),
    "tab" => "general",
    "type" => "font",
  ),

  …

);

The file defines an array called $less_user_variables, with each element’s array key being the name of the LESS variable, and the value being another array having this form:

array(
  "value" => default value of the theme option,
  "description" => description shown beside the theme option's field,
  "tab" => which tab the option appears on, one of:
    "general", "buttons", "forms", "calendar", "posterboard",
    "month", "stream" (Pro only), or "agenda",
  "type" => the option's data type, either "color" or "font",
);

So for example, Vortex makes use of the baseFontFamily option above in its less/style.less file in this way:

.timely {
  …
  font-family: @baseFontFamily;
  …
}

The Umbra theme provides its own version of user_variables.php, which is identical to Vortex’s user_variables.php except that it provides a different default value for each theme option (the "value" element in the above array), effectively creating an entirely different calendar theme simply by providing different default color settings.

If you wish to add your own additional theme options to use in your custom child theme’s override.less file, then you should copy Vortex’s less/user_variables.php file into the same location in your child theme’s directory.

Full listing of core LESS rules

If you wish to get a broader sense of what LESS rules are used by the calendar, feel free to have a browse through these core styling files in the Vortex theme:

The sections in these files are separated by CSS comments, so if you are curious as to how a particular calendar view or element is styled, it should be possible to find out by locating the relevant section.

Template Files

Themes can also contain overridden template files (similar to template files used by standard WordPress Themes). These are the files that are responsible for most of the HTML markup produced by the calendar plugin.

By default, the theme engine uses the core template files found in the Vortex theme. Here is a summary of these files and their uses:

If you wish to change the markup produced by one of these files, you may copy the relevant template file contained in vortex into your child theme’s directory, then make your changes. If present, the theme engine will choose your theme’s version of the template file over Vortex’s.

If you have upgraded your calendar and your child theme uses overridden template files, we recommend you back up your templates and remove them from your child theme. Try using your calendar, and if changes are needed, copy the latest version of the template from vortex to your child theme’s directory and then make your revisions.

JavaScript

The JavaScript code used by Vortex is contained entirely in the core plugin, and JavaScript files cannot be overridden by a custom theme.

In version 1.9 of the plugin, all JavaScript functions have been fully namespaced in the global window.timely object (with the help of the RequireJS-based JavaScript build system). Not only are all JavaScript functions private to the namespace object, but all JavaScript code is also compressed to save space and optimize performance.

In a future version of the plugin, the core JavaScript code may support hooks so that internal callbacks can be triggered from external sources, as well as allow custom callbacks to be executed when particular internal events occur.