Themer’s Guide: The Events Calendar/PRO 3.0

Events 3.0 Themer’s Guide

Table of Contents:

Customizing Template Files

The Events Calendar comes with a number of template files that determine how the plugin looks and behaves; we call these views. In addition to creating a new Page Template, you can override these files with custom files that you place in your theme. It’s important that you don’t edit the view files directly in the plugin, you should copy them into your theme first, and edit them there. This will ensure that any modifications you do make will not be overwritten by updating the plugin. The Events Calendar will ensure that your modified files, in the correct folder, will override the plugin files.

Let’s take a look at how it’s done:

1. Create a new folder in your theme

Open your theme folder, located at wp-content/themes/your-theme/.

Create the following folders:

  • To modify The Events Calendar and The Events Calendar Pro create the folder
    /tribe-events/

  • To modify an add-on (for example, the community add-on) create the folder
    /tribe-events/community/
    /tribe-events/pro/
    /tribe-events/wootickets/

2. Locate the files you wish to edit

The template view files are located in the following places:

  • The Events Calendar template files
    /wp-content/plugins/events/views/

  • The Events Calendar Pro template files
    /wp-content/plugins/events-calendar-pro/views/

  • The Community add-on template files
    /wp-content/plugins/events-community/views/

You can also modify the selected template’s markup to adjust things as well. To do that first find out what template you are using in Events –> Settings –> Display. If you have selected the Default Events Template, the plugin will use the /wp-content/plugins/the-events-calendar/views/default-template.php template file for the display. You can override and edit this by making a copy and placing in an ‘tribe-events’ folder in your theme.

All of the other Events Template options will use one of your available theme page templates (page.php, full-width.php, etc.) which you can also edit.

Based upon what Events Template option you’ve chosen, you will need to use these conditional wrappers to help you conditionally display or not display certain markup on each corresponding events page.

Example Customization

Let’s take a look at an example of a very simple template view customization. This should give you an idea of the workflow.

By default, The Events Calendar displays just the venue name underneath each event date, here’s what it looks like:

But what if you also want to show the event organizer, so it looks like this? 

Here’s how it’s done:

    1. Copy /wp-content/plugins/events/views/list/single-event.php to your-theme/tribe-events/list/single-event.php (replace “your-theme” with the name of your theme)

    2. Edit your-theme/tribe-events/list/single-event.php, and add the following underneath the venue details:

      <p>Organized by: <?php echo tribe_get_organizer(); ?></p>

    3. Save, and you’re done!

Every template view customization follows that basic pattern of copying the file you wish to edit to your theme folder and then customizing the copied file. This protects your edits whenever you update The Events Calendar and its add-ons. Remember! If you change your WordPress theme you’ll need to copy all of your customizations to the new theme’s folder.

You’re now set up to start customizing The Events Calendar.

Views & Templates

The Events Calendar

Month View

  • month.php - Wrapper for the month view template, includes the tribe bar and then the month content template
  • month/content.php - Main content template for month view, contains the title, includes the nav template, the grid loop, and the footer. This is the template that’s used to return ajax requests navigating and filtering results on month view
  • month/nav.php - Contains the next and previous links
  • month/loop-grid.php - Contains the loop structure that loops through all the days in the month, includes the single day template
  • month/single-day.php - Contains the day number and a loop for the events in each day, includes the single event template
  • month/single-event.php - Contains a single event in month view

List View

  • list.php - Wrapper for the list view template, includes the tribe bar and then the list content template
  • list/content.php - Main content template for list view, contains the title, includes the nav template, the events loop, and the footer. This is the template that’s used to return ajax requests navigating and filtering results on list view
  • list/nav.php - Contains the next and previous links
  • list/loop.php - Contains the structure for the loop of events. Includes the single event template
  • list/single-event.php - Template for a single event in list view

Widgets

  • widgets/list-widget.php - Template for the list widget included with the free Events plugin

Tribe Events PRO (premium)

Map View

  • map.php - Contains the overall wrapper markup for map view, includes the template for the Google Map container
  • map/gmap-container.php - Contains the empty HTML element that gets populated with the Google Map via javascript
  • map/content.php - Main content template for map view, contains the title, includes the nav template, the events loop, and the footer. This is the template that’s used to return ajax requests navigating and filtering results on map view
  • map/nav.php - Contains the next and previous links
  • map/loop.php - Contains the structure for the loop of events. Includes the single event template
  • map/single-event.php - Template for a single event in map view

Photo View

  • photo.php - Wrapper for the photo view template, includes the tribe bar and then the photo content template
  • photo/content.php - Main content template, contains the title, includes the nav template, the events loop, and the footer. This is the template that’s used to return ajax requests navigating and filtering results on photo view
  • photo/nav.php - Contains the next and previous links
  • photo/loop.php - Contains the structure for the loop of events. Includes the single event template
  • photo/single-event.php - Template for a single event in photo view

Day View

  • day.php - Wrapper for the day view template, includes the tribe bar and then the day content template
  • day/content.php - Main content template, contains the title, includes the nav template, the events loop, and the footer. This is the template that’s used to return ajax requests navigating and filtering results on list view
  • day/nav.php - Contains the next and previous links
  • day/loop.php - Contains the structure for the loop of events. Includes the single event template
  • day/single-event.php - Template for a single event in day view

Week View

  • week.php - Wrapper for the week view template, includes the tribe bar and week content template
  • week/content.php - Main content template, contains the title, includes the nav template, the events loop, and the footer. This is the template that’s used to return ajax requests navigating and filtering results on the week grid loop views
  • week/loop-grid.php - Wrapper for the grid loop, contains the week grid day headers
  • week/loop-grid-allday.php - Contains the column structure for the loop of all day events. Includes the single event all day template
  • week/loop-grid-hourly.php - Contains the column structure for the loop of hourly events. Includes the single event hourly template
  • week/nav.php - Contains the next and previous links for navigating between weeks
  • week/single-event-allday.php - Template for a single all day event, includes the event tooltip template
  • week/single-event-hourly.php - Template for a single hourly event, includes the event tooltip template
  • week/single-event-tooltip.php - Template for the hover tooltip for expanded event information

Venues and Organizers

  • single-organizer.php - Used to list upcoming events related to an individual organizer. This utilizes the list templates for the display of any related upcoming events
  • single-venue.php - Equivalent to the single-organizer.php template but targeting venues, again this utilizes list templates to display any related events

Widgets

  • pro/widgets/countdown-widget.php - Contains the countdown widget
  • pro/widgets/list-widget.php - Contains the list widget included with the premium Events PRO plugin: this overrides any existing template at widgets/list-widget.php (outside of the pro subdirectory) however, that template will still be respected up until it is removed or a new one is created within the pro subdirectory
  • pro/widgets/mini-calendar-widget.php - Wrapper for the mini calendar widget. Includes the mini calendar grid template and the mini calendar list template
  • pro/widgets/mini-calendar/grid.php - Contains the grid (calendar month) portion of the mini calendar widget. Includes the single day template
  • pro/widgets/mini-calendar/single-day.php - Contains a single day in the mini calendar widget. Includes the single event template
  • pro/widgets/mini-calendar/single-event.php - Contains a single event in the mini calendar widget
  • pro/widgets/venue-widget.php - Contains the venue widget

Ticketing Plugins (e.g. WooCommerce Tickets, EDD Tickets, WPEC Tickets)

  • attendees-email.php - Template for the email you get with the attendee list for an event.
  • email.php - Template for the email the customers get when they purchase tickets for an event. This email is the actual ticket people will use at the door of your event.
  • tickets.php - Table of tickets with the button to purchase in the front end. It shows in the event single, if the event has tickets to sell.

Community Events

  • edit-event.php - The template for event submission for community events
  • event-list.php - The template to list logged in user’s events on the front end
  • edit-organizer.php – The template for editing Organizers for community events
  • edit-venue.php – The template for editing Venues for community events

Customizing Styles

There are two distinct ways to customize the look of your events pages:

  • Adding custom styles alongside our default stylesheets - this method is best used when you have just a few changes you’d like to make to the events pages styles.
  • Replacing the default stylesheets with your own - this method is best used when you’d like customize a majority of the events pages styles.

Adding Custom Styles

The Events Calendar offers 3 default style options to choose from:

  • Skeleton Styles - Includes only enough CSS to achieve complex layouts like calendar and week view
  • Full Styles - More detailed layouts, relying heavily on your theme’s typography and colors
  • Tribe Events Styles - A fully design and styled theme for your events pages, from yours truly

Similar to how template files are overwritten, you can place appropriate files in your theme inside a folder called tribe-events/ to load your own stylesheets. This allows you to load a stylesheet in your theme that only contains the custom styles you need without having to duplicate one of our own as a starting point, or using an @import rule. Keep in mind that when you put a custom stylesheet in the tribe-events folder, it will be loaded in addition to our stylesheets. This differs from placing custom templates in that folder, which replace our templates.

Loading Custom Styles for The Events Calendar

  • To load custom styles for  core views and elements, create a stylesheet called tribe-events.css in the tribe-events/ directory of your theme.

Loading Custom Styles for The Events Calendar PRO (premium)

  • To load custom styles for  PRO views and elements, create a stylesheet  called tribe-events-pro.css in the tribe-events/pro/ directory of your theme.
  • To load custom styles for the Events Calendar widget, create a stylesheet  called widget-calendar.css in the tribe-events/pro/ directory of your theme.

For Example:

Let’s say you’d like to add a small style tweak that changes the background color of the event meta box on an single event from gray to white. In tribe-events.css in the tribe-events/ directory of your theme, you can simply add:

.single-tribe_events .tribe-events-event-meta {
    background: #fff;
}

Replacing Default Stylesheets

If you’d like to replace the default stylesheets offered by The Events Calendar, you can use any of the filters we have provided to do so:

  • tribe_events_stylesheet_url (The Events Calendar core styles)
  • tribe_events_pro_stylesheet_url (The Events Calendar Pro styles)
  • tribe_events_pro_widget_calendar_stylesheet_url (The Events Calendar calendar widget styles)

For example:

Let’s say you want to replace the custom core and PRO stylesheets offered by the plugin and load your theme’s own stylesheets called custom-events-stylesheet.csts and custom-events-pro-stylesheet.css respectively. You can use the aforementioned filters like this:

function replace_tribe_events_calendar_stylesheet() {
   $styleUrl = get_bloginfo('template_url') . '/custom-events-stylesheet.css';
   return $styleUrl;
}
add_filter('tribe_events_stylesheet_url', 'replace_tribe_events_calendar_stylesheet');

 

function replace_tribe_events_calendar_pro_stylesheet() {
   $styleUrl = get_bloginfo('template_url') . '/custom-events-pro-stylesheet.css';
   return $styleUrl;
}
add_filter('tribe_events_pro_stylesheet_url', 'replace_tribe_events_calendar_pro_stylesheet');

Note: The default Tribe stylesheet will continue to load in addition to the custom one you defined above, unless you set the Default stylesheet to something other than Tribe Events Styles. In the Admin control Panel, under Events -> Settings -> Display (tab), change ‘Default stylesheet used for events templates’ to Skeleton Styles if you would like to fully replace the default styles.

Responsive Templates

There are several key areas to be aware of regarding the responsiveness of the events templates, especially if you plan to customize how this component works.

Breakpoints

The default breakpoint at which the responsiveness kicks in for smaller devices is 768px. This breakpoint can be customized or completely killed by utilizing the following filters:

  • tribe_events_mobile_breakpoint – Will allow you to edit the breakpoint
  • tribe_events_kill_responsive - Will remove all responsiveness

For example: Let’s say you want to customize the responsive breakpoint to be 600px. You can use the tribe_events_mobile_breakpoint filter like this:

function customize_tribe_events_breakpoint() {
    return 600;
}
add_filter( 'tribe_events_mobile_breakpoint', 'customize_tribe_events_breakpoint' );

Now let’s say you want to remove the responsiveness altogether. You can use the tribe_events_kill_responsive filter like this:

add_filter( 'tribe_events_kill_responsive', '__return_true');

Lastly, we have provided a couple of body classes for you to utilize as needed:

  • .tribe-is-responsive – This is added if the breakpoint hasn’t been killed
  • .tribe-mobile – This is added once you reach the responsive breakpoint breakpoint

CSS

Aside from the retina / hdpi media queries (used for icons only), the responsive CSS has been broken into it’s own stylesheets (*-mobile.css). You will find that each stylesheet option, except for skeleton, includes a mobile stylesheet for both Core and PRO plugins, which contains the CSS necessary to style the responsive templates.

You can see the above section, Customizing Styles, regarding how to work with the newly added responsive stylesheets as this information applies to these stylesheets as well.

Lastly, an additional media query has been included at a max-width of 600px to deal specifically with some of the tickets add-ons and photo view in some of the responsive stylesheets.

JS

Javascript is used as a helper for some of the mobile functionality, and is heavily used for both month and week views. We have also taken an important and significant step in utilizing javascript templates to power the mobile areas for the month and week views as well as to power the overall plugin tooltips.

If you have overridden:

  • views/month/content.php
  • views/pro/week/content.php

You will need to update your templates with the latest template code from at least version 3.5 for Core and PRO plugins to make sure you have the various new includes necessary for this functionality.

If you would like to better understand how the javascript templating works or need to customize these templates please refer to our guide on the Javascript Templating.

Lastly, if you have overridden the markup of your tooltips, you’ll need to port these over to the JS template, which includes in-depth instructions.

Templates

(Applies to users upgrading to version 3.5 of the Core and PRO plugins)

You’ll want to check over any modifications made, whether that is template or style overrides, or if you’ve also done your own mobile version. Be sure to test your modifications against all the new updates.

You’ll definitely need to update your overridden templates, and potentially the default breakpoint and/or mobile CSS and/or overridden CSS to add the default responsive CSS, but as always you can turn to support if you have any other questions during this process.

Javascript Templating

As of version 3.5 we have begun using some very simple javascript templating to power both the mobile events templates and the tooltips for the month and week views. They are fairly straightforward to follow and understand, and we have also provided detailed inline documentation to help you if you need to customize either part.

You will find these templates, along with their inline documentation and additional helpers, for the following:

Core Documentation: core/views/month/single-event.php
PRO Documentation: pro/views/week/single-event-allday.php

Mobile Templates:

  • core/views/month/mobile.php
  • pro/views/week/mobile.php

Tooltip Templates:

  • core/views/month/tooltip.php
  • pro/views/week/tooltip.php

You can see the above section, Customizing Template Files, regarding how to work with these newly added templates as this information applies to these templates files as well.

Modern Tribe Newsletter

Insight, Discounts & Notices for People Who Kick Ass..