Building a WordPress Theme Around the Events Calendar Plugin

WordPress has quickly transformed from a mere content management platform to one that is now involved in managing almost every aspect of an administrator’s day. The world’s most popular content management solution can, via plugins, manage events, dates, to-do lists, notes, tweets, Facebook status updates, and more. And, of these new ways to manage content, there is perhaps no more popular plugin than The Events Calendar, widely known as the most popular, highest-rated, and most function plugin for managing dates within WordPress, the plugin allows administrators to print public calendars in a grid-based month format as well as a list-based daily format, and allows single-event pages to be displayed just like single entry pages within the WordPress software.

The Events Calendar Plugin

All of these features are just begging to be themed and, indeed, users have begun customizing templates to meet the needs of the Events Calendar. Creating themes for sites for this plugin is essentially twofold. First, the plugin is placed within a site’s existing design and it displays its event-based content in the same part of a website where entries are shown. That means it must be seamlessly integrated into the main content area of a website. But, above and beyond that, The Events Calendar includes its own set of variables for displaying things like the month name, the day of the week, and the “next month” or “last month” links for navigating the full scope of the event calendar itself.

The Events Calendar Plugin

That means that the calendar can be themed independently of the website, and the website can actually be themed without so much as a single edit to the calendar templates. Here’s how to create a WordPress website that is receptive to The Events Calendar; also included is a basic primer on how to modify the templates that ship with the plugin so that they can be made to conform to a site’s existing appearance.

Build a WP Theme Using the Events Calendar Plugin

Step 1: Understanding How The Events Calendar Displays Itself on the Production Site

The Events Calendar is easily one of the most unique plugins of any sort for WordPress. Rather than requiring a variable to be placed within a template file in order for the content to be seen, the plugin actually creates an entirely new page and permalink structure to display its month, week, and day views, as well as individual event pages. That’s fairly bold, but it’s actually a good thing for users. First and foremost, this means that The Events Calendar uses the existing website’s template to display its information. It will look seamless from day one (unless it doesn’t that is why you’re reading this tutorial) and users will find using the calendar to be as intuitive as using the rest of the website.

Unfortunately, if site administrators manually link to each of their WordPress pages within the navigation bar, they’ll need to update the header.php template file to include a link to The Events Calendar from within their WordPress installation. The link to the individual event calendar pages can be found in the Events Calendar settings. Those settings can be accessed by clicking the new “Events” heading in the Dashboard sidebar and then electing to edit Events Calendar preferences. There, users can preview the settings and view the permalink structure that they will be using. Once that has been decided and set, the new link can be added to the site’s navigation, allowing readers to see the calendar view upon landing at the site’s index page.

This would be the time to make sure that the calendar is not too wide, and the page is not too narrow, for optimal viewing conditions. Remember that a typical “grid” calendar that displays a full month’s view must be relatively wide in order to display event titles and times. If the page is not wide enough for the calendar, the site’s design must be revised ‘outward’ to accommodate the new plugin’s content.

Aside from the width of the page, there aren’t many other avenues for design conflict with it comes to The Events Calendar as a successful plugin. From here, any design editing will have to be done with the actual Events Calendar themes themselves; those themes can be a bit extensive, so it’s worth noting each of the files that are available to be customized.

Step 2: Learning the Events Calendar Template File Structure

Because The Events Calendar is not a basic plugin, it does not ship with a particularly basic template system, either. The plugin contains a good number of templates, each pertaining to a different function of the software. Ranging from the grid-based format to a template dedicated solely to a single day’s events (or lack thereof), these templates are extensive and come with their own set of variables. But before those variables can be explained, the templates themselves must first be elaborated on. So, in short, here is the name of each template followed by what it is responsible for accomplishing within the scheme of the Events Calendar plugin:

  • events-list-load-widget-display.php : This template is actually not for the website at all, in a traditional sense, and instead controls the display of the Events Calendar widget. It can certainly be changed, but it probably doesn’t have to be.
  • full-address.php : This displays an event address and, optionally, a Google Map of the event’s location if the user selects to display it to their readers.
  • gridview.php : Displays a traditional calendar-style view of a full month’s events.
  • list.php : Displays all former and future events in a neatly-styled and compact list fomat.
  • single.php : The full “single event” template that contains information about the event’s starting an ending time, address, a description of the event, and who has been invited and decided to attend, decline, or table the decision.
  • table-mini.php : An optional “mini widget” template that can be used to overwrite the standard widget template at the user’s discretion.
  • table.php : This template displays the days of the month in the grid view template, and its inclusion is optional with The Events Calendar plugin.

It’s easy to see how extensive the list of templates available to this plugin is, and it’s also easy to see how easily every aspect of The Events Calendar can be customized to match a site’s design and an administrators’ preferences as to what is displayed to users and how it appears. This might seem daunting, but most advanced users will find the extensive list of templates to be as helpful as a typical WordPress theme’s long list of files. With each template being a known quantity, here are the variables that every user will need to know when developing their own Events Calendar theme to blend seamlessly with their website’s overall design.

Step 3: Getting Acquainted with the Events Calendar Variables and Putting Them to Use

Just like a typical WordPress Loop, the Events Calendar plugin has a few of it sown variables that can be used in standard XHTML and CSS to create a rich interface that appeals to users and blends into a site’s existing design. These variables are pretty straightforward and semantically easy, but it’s worth noting what each one does on its own. Here are the variables that users will be manipulating when creating an Events Calendar theme.

<?php echo tribe_get_previous_month_link(); ?> and <?php echo tribe_get_previous_month_text(); ?> : Creates a link to the previous months’ calendar.

<?php echo tribe_get_next_month_link(); ?> and <?php echo tribe_get_next_month_text(); ?> : Creates a link to the next month’s calendar.

<?php tribe_calendar_grid(); ?> : Creates the grid-style month view for events.

<?php echo tribe_get_ical_link(); ?> : Provides a link to the ICS file for importing to iCal and Google Calendar, among others.

<?php the_title() ?> : This is used to show the event’s name or title.

<?php echo tribe_get_organizer_phone(); ?> : Shows event administrator’s phone number.

<?php echo tribe_get_organizer_email(); ?> : Shows the event administrator’s email address.

<?php echo tribe_get_map_link(); ?> : This variable produces a Google Map of the event’s location as well as the printed address of the event.

<?php echo tribe_recurring_event(); ?> : This variable is used to show whether an event repeats on a daily, weekly, monthly, or yearly basis.

Step 4: Creating a Proper Template Header for an Events Calendar Theme

WordPress themes are notorious for including a brief bit of commented information at the top of the file so that they can be easily identified by users through the WordPress Dashboard. The Events Calendar has taken a similar approach to crafting their own template files, but instead of essential information separated into lines of content, they have instead elected to have each template file contain a brief description of the template’s purpose. An example is provided below:

/**
* A single event. This displays the event title, description, meta, and
* optionally, the Google map for the event.
*/

This is the default description placed into the single.php file included with The Events Calendar (Free Edition) from the WordPress.org Extend plugin gallery. This information must be included at the top of each plugin file. Furthermore, the following line of PHP code must be placed into every template in order to open the variables to parsing by The Events Calendar. This is much like placing a “WordPress Loop” into the main site’s templates. Failure to include this PHP code into the template will result the variables going unparsed:

&lt;?php if ( !defined('ABSPATH') ) { die('-1'); } ?&gt;

Step 5: Maintaining File Structure and Overwriting Existing Templates

There is no such thing as “multiple themes” for the Events Calendar plugin as it currently exists. Instead, users must make note of the existing file structure included in the “views” folder that contains the template files and then overwrite every single template file when customizing them. This is a bit archaic, but the simple fact of the matter is that themes don’t get modified by the vast majority of plugin users and the developers have simply seen no reason to include a full tempting system.

With the variables and file structure mastered, and changes made, the files can be saved the changes will be reflected immediately on the production website. The Events Calendar will now blend seamlessly into a website’s existing WordPress template, making the new calendar user-friendly for site readers of all experience levels.

Author: (40 Posts)

Vladislav Davidzon is the principal of US-based online marketing consultancy Vladislav Davidzon & Associates, developing integrative solutions through high impact search engine optimized WordPress websites for socially responsible customers of all sizes around the world.

Comments