How to Create Custom Calendar Themes

Calendar "Main" view vs "Satellite" views

Main Calendar Views

There are two different ways to create and place a calendar module on a site. When a calendar is made, it will appear in the "Add and Arrange Modules" interface in the Page Editor, under the "Calendars" list. By placing this module on a page, you are creating the "Main" view of the calendar. This module has two potential views (not including the Edit Event view) that will be displayed, depending on what URL parameters are passed to the page on which the module sits:

  • search_view (default view). Default template: calendar-listevents.tpl
  • view_event: (shows a single event's details). Default template: calendar-viewevent.tpl

The default view for the main calendar module is a search_view showing a search result based on the current date - and showing all upcoming events (not showing events that have occurred in the past).

Satellite Calendar Views

It is also possible to create additional views of a given calendar by instantiating a calendar view using Smarty. Example:

{execModule name="OpsCalendar" view="mini_view" calendarid="12" template="calendar_miniview.tpl"}

There is a Content Manager module called "Calendar View" that allows you to create "Monthly View", "Weekly View" and "List View" modules that utilize this method. These modules are referred to as "satellite" modules because their default templates require a URL reference to the main calendar view in order to show the full details of event data. The way that the URL reference to the main calendar is made, is that when requested, Rivista will search through all of the pages in the system, looking for the calendar module, and when it finds the calendar module, it will stop and return that page as the location of the main calendar. However, if you specify the additional "calendarpageid" parameter and provide the id of the page you want to use, Rivista will use that page for all calendar links. If the main calendar module is placed on more than one page, you may get unexpected results - therefore it is recommended that only one instance of the main view of a given calendar be placed on a site unless you use the calendarpageid parameter to specify the page to use.

Creating Calendar Themes and Working with Templates

Calendar Themes

The Calendar module uses a large number of templates to render data in a variety of ways. A complete Calendar theme would be a collection of all of these templates. To create a local theme, create a folder in the /templates/includes directory of a Rivista-powered site, and name the folder, "caltheme_mytheme" replacing "mytheme" with a unique string that describes your theme. The default theme is located in /core/media/templates/caltheme_default/ and has the following templates. Files in your local theme that have names that match the ones indicated below, will be used in all associated views for that given calendar (including satellite modules). It is not required to create versions of each template in the default theme for your local theme. In fact, you could create a theme that has only one of the templates indicated below. All un-named templates will utilize the default template. Templates in italics are not being actively referenced elsewhere in the code base, but are offered as options for some views:

Theme Templates

  • calendar_day_ajax.tpl - Default template for "day_view"
  • calendar_day_full_local.tpl - Optional template intended for "day_view" in a "mini_view" that does not link to a main calendar (shows all calendar data locally, within the module). Also, shows event image and description (but not custom fields).
  • calendar_day_local.tpl - Optional template intended for "day_view" in a "mini_view" that does not link to a main calendar (shows all calendar data locally).
  • calendar_day.tpl - Default template for displaying the "day_view" by the "Monthly View" module type when "Show event descriptions" option is set to "No".
  • calendar_event.tpl - Default template for displaying the data from a single event. Referenced by calendar-viewevent.base.tpl.
  • calendar_eventdatedetails.tpl - Used for showing recurring date information. Referenced by several default templates.
  • calendar_events_search_results_columns.tpl - Optional search results template. Shows events in rows, sortable by columns of: Date/Time, Event Title, and City. Also has a 4th, non-sortable column that displays categories applied to the event.
  • calendar_events_search_results.tpl - Default search results template. Referenced by calendar-listevent.base.tpl
  • calendar_main_links.tpl - Default menu for main calendar view. Referenced by calendar-listevents.base.tpl and calendar-viewevent.base.tpl.
  • calendar_mini_view_event.tpl - Default event view for the AJAX "mini_view". Referenced in /core/ajaxserver.php. Can be overridden.
  • calendar_miniview.tpl - Default template for the AJAX "mini_view".
  • calendar_monthly_grid_ajax.tpl - Default template for the grid portion of the AJAX "mini_view". Referenced by calendar_miniview.tpl.
  • calendar_monthly_grid_local.tpl - Optional template for displaying monthly data from a "mini_view". Does not use AJAX calls to show day_view data, but instead uses local (self-referencing) links.
  • calendar_monthly_navigation_ajax.tpl - Template snippet showing "Previous | Current | Next" month navigation for an AJAX powered "mini_view". Referenced by calendar_miniview.tpl.
  • calendar_monthly_navigation_local.tpl - Optional template snippet for showing "Previous | Current | Next" month navigation for a "mini_view". Links are not AJAX, but instead reference the same page as the module.
  • calendar_print-viewevent.tpl - Default template for showing an event in print mode.
  • calendar_search_filters.tpl - Default template for showing the search form for a calendar. Referenced by calendar-listevents.base.tpl
  • calendar_view_error.tpl - Default error template, used by OpsCalendar class.
  • calendar_weekview.tpl - Default "week_view" template.
  • calendar-editevent.base.tpl - Default template for editing events. Referenced by calendar-editevent.tpl.
  • calendar-editevent.tpl - Default parent template for editing events. Used by the doEdit() method in OpsCalendar class.
  • calendar-editeventdates.base.tpl - Default template for editing event dates. Just a wrapper that in turn references admin/media/templates/calendar-editeventdates.base.tpl. Is referenced by calendar-editevent.base.tpl.
  • calendar-editeventnotifiyemail.tpl - Default email template used when notifying calendar administrators that an event has been edited.
  • calendar-listevents.base.tpl - Default template for showing search results in the default main calendar module view. Referenced by calendar-listevents.tpl.
  • calendar-listevents.tpl - Default template for the "search_view" in the main calendar module view. A wrapper for calendar-listevents.base.tpl.
  • calendar-neweventnotifyemail.tpl - Default email template used when notifying calendar administrators that a new event has been submitted.
  • calendar-viewevent.base.tpl - Default template used for showing the event details in the main calendar. Referenced by calendar-viewevent.tpl.
  • calendar-viewevent.tpl - Default template used for showing "event_view" in the main calendar. A wrapper for calendar-viewevent.base.tpl.

Calendar Views

The calendar module can retrieve data from the database and make it available to the template layer in a variety of formats. Here is a list of available views of calendar data:

  • view_event: The display of data for a single event
  • week_view: The display of data for a week's worth of events
  • mini_view: The display of data for a month's worth of events
  • day_view: The display of data for a day's worth of events
  • search_view: The display of data for a results of a search

Each of these views can be supplied as arguments to the instantiation of a calendar module, as described below:

Instantiating a Calendar View

As mentioned above, a calendar view can be instantiated via Smarty, by using the following syntax:

{execModule name="OpsCalendar" view="mini_view" calendarid="12" template="calendar_miniview.tpl" calendarpageid="1234"}

Required parameters are "name", "view", and "calendarid". Optional is a calendarpageid parameter used to specify which page to use for building links to the Calendar. By supplying a "template" argument, you may also customize the template used for that view. So, you could create your own local "week_view" template (which may even be outside of any established themes) and call it like this:

{execModule name="OpsCalendar" view="week_view" calendarid="12" template="my_weekview.tpl"}

Note that you can use this method to mix and match different calendar views together into one view. You could also use this method for modifying the default views of the main calendar (or any other default view). Here is an example of how to make a monthly grid calendar that does not use AJAX to reference the main calendar (in essence, skipping the requirement to have a "main" calendar placed on the site):

  1. Create a template named "module.calendarview.myview.tpl" This will make this template available to the "Calendar View" module in the Content Manager. Place this template in the local /templates/includes/ directory of the site you are working on.
  2. Create another template named "mymonthlyview.tpl" and put this also in your /templates/includes/ directory.
  3. Inside "module.calendarview.myview.tpl" put the following code:
    <div class="calendar">
    {if isset($Page->params.event)}
        <a href="{$Page->path}">&laquo; Return to today's events</a>
        {execModule name="OpsCalendar" view="view_event" calendarid=$module.calendarid template="calendar_event.tpl"}
        {execModule name="OpsCalendar" view="mini_view" calendarid=$module.calendarid template="mymonthlyview.tpl"}
        {execModule name="OpsCalendar" view="day_view" calendarid=$ template="calendar_day_full_local.tpl"}

    You will notice that we are telling the module to use our "mymonthlyview.tpl" template to render the results of the "mini_view".
  4. Inside "mymonthlyview.tpl" put the following:
    {addcss file="calendar-month-view.css" order=1}
    <div class="monthly-calendar">
        {include file="calendar_monthly_navigation_local.tpl"}
        {include file="calendar_monthly_grid_local.tpl"}

Using the above method, you will then have a monthly grid calendar that has no dependency on any "main" calendar being placed elsewhere on the site.

If you wanted to be really sneaky, you can also override the default views of the main calendar by creating local versions of one or more of the default templates used by the main calendar and instantiating new views within those templates. Try this, and see what happens:

  1. Create the "mymonthlyview.tpl" template as described above, and put it in your /templates/includes/ directory.
  2. Create another local template and call it, "mysearchview.tpl" and put it in your /templates/includes/ directory.
  3. Put the following code in the "mysearchview.tpl" template:
    <div class="events-search-results">
        {include file="calendar_events_search_results_columns.tpl"}
  4. Create a local theme folder as outlined above
  5. Inside this folder create a file called, "calendar-listevents.tpl" (The default template used in the main calendar).
  6. Inside this file put the following code (note that this method requires the use of the "mymonthlyview.tpl" as described above):
    {if isset($Page->params.submit)}
    <a href="{$Page->path}">&laquo; Return to today's events</a>
        {include file="calendar_search_filters.tpl"}
        {execModule name="OpsCalendar" view="search_view" calendarid=$ template="mysearchresults.tpl"}
        {execModule name="OpsCalendar" view="mini_view" calendarid=$ template="mymonthlyview.tpl"}
        {include file="calendar_search_filters.tpl"}
        {execModule name="OpsCalendar" view="day_view" calendarid=$ template="calendar_day_full_local.tpl"}
  7. Apply this new theme to your calendar.
  8. Place the "main" calendar on a page, and take a look.
Have more questions? Submit a request


Powered by Zendesk