There are a number of different approaches that you can take to customizing your events calendar. Use this guide to learn all about them so you can make your events calendar look beautiful and integrate seamlessly with your WordPress theme.
The approaches are:
But first, a bit about how The Events Calendar displays your content:
The events framework utilizes custom loops and rewrite rules to generate the overall functionality and display. This means that, rather than dropping a shortcode into a page, specific functionality is tied to an associated url.
For example, when you have pretty permalinks turned on you can find the calendar grid view at /events/month/ and the list view at /events/upcoming/. The visual output is controlled through a series of views, which are PHP template files containing markup and additional plugin-specific functions.
Warning: we advise that you don’t edit the plugin files in their original location. If you do, your edits will be overwritten with any new updates. Instead, you should copy files that you wish to edit. As you’ll see, we’ve made this very easy for you to do.
1. Edit the Before & After HTML
Navigate to Events > Settings > Templates. There are two boxes here, one for adding HTML before the calendar, and the other for adding HTML after.
You could use these areas to both apply styles to your calendar or to call PHP functions. You could even just add simple HTML to append or prepend text to every calendar.
Tips
- You do not need to add doctype declarations and head elements. Just add the divs and other code you need.
- Check out this gist to add TinyMCE to the Before/After HTML fields
2. Page Templates
You can use a custom Page Templates to display your events. It may be that a Page Template came packaged with your WordPress theme. Or you might want to use one that you’ve created yourself.
When a Page Template is selected it will determine the layout of the header, sidebar, main content, footer and any other content.
To assign a Page Template visit Events > Settings > Templates.
The Events Template dropdown will contain the following:
- The default WordPress page template – page.php
- The default Events template that comes with the plugin –
ec-page-template.php&ecp-single-template.php - Any other page templates available in your theme.
To Create a New Page Template
The simplest way to create a new Page Template is to make a copy of page.php and make your edits in there.
Let’s take a look at how it’s done:
1. Locate page.php
page.php is located in your theme folder. You’ll find it at wp-content/themes/your-theme/page.php (where /your-theme/ is the name of your active theme).
2. Duplicate page.php
Create a duplicate of page.php and rename it.
3. Add the Template name and description
When you create a new Page Template you must define it for WordPress. Open the new template file and in the comments at the top add:
/* Template Name: My New Page Template Template Description: A custom template for making my events calendar look gorgeous and kick ass. */
Tip: WordPress reserves a number of names for its own template files. Make sure not to use any of these. A complete list of these can be found in the Codex.
That’s it! Once your template is saved, WordPress will pick it up and it will be displayed in the Events Templates dropdown.
3. Customizing The Events Calendar Template Files
The Events Calendar comes with a number of template files that determine how the plugin looks and behaves; we call these views. As well as creating a new Page Template you can modify these files. But before you do it’s important that you move them to a new folder. This will ensure that any modifications you do make will not be overwritten by updating the plugin. The Events Calendar will ensure that the modified files, in the correct folder, will override any plugin files.
Let’s take a look at how it’s done:
1. Create a new folder
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
/events/ - To modify the Community add-on create the folder
/events/community/
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/community/views/
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 a toggle button that lets your users flick between the calendar views. Here it is:
But what if you only want your visitors to see the calendar view? You’d need to remove the toggle. Here’s how it’s done:
- Copy
gridview.phpto your themes folder. Open the view folder and findgridview.phpat/wp-content/plugins/events/views/gridview.php. Make a copy of this file and place it in the folder/wp-content/themes/your-theme/events/(replacing “your-theme” with the name of your theme). - Edit gridview.php. Open
gridview.php, find lines 35-38 and remove them.
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.If you’d like to see more specific examples on customizing your template views, you may find the following useful:
- How To Show Featured Thumbnails in The Next Events Widget
- Add the Post Thumbnail to Your Event List
- How can I remove the buttons to toggle between grid/list on the front end?
- How To Hide Events From Unregistered Users
You’re now set up to start customizing The Events Calendar. To help you out, here’s a list of all of the template view files and what they do:
| File | Description |
|---|---|
| ecp-page-template.php (see note above) | This file determines the overall page wrapper template to be used for all main views. |
| ecp-single-template.php (see note above) | This file determines the page wrapper template to be used for all single event views. |
| events-list-load-widget-display.php | This file controls the display for the Events List Widget. Note: if you have the Pro plugin activated editing this file will do nothing because the Events List Widget is replaced by the Events Advanced List Widget controlled by the events-advanced-list-load-widget-display.php file described below. |
| full-address.php | This file displays the event address in the single event pages. |
| gridview.php | This file is partly responsible for the calendar page display (table.php file is the actual file that spits out the calendar). It doesn’t actually output the calendar but is more used for the calendar prev/next links, month/year drop downs and calendar toggle buttons. |
| list.php | This file controls the list view of events including the single day view. |
| single.php | This file controls the view of single events. |
| table-mini.php | This file controls the display of the small calendar widget. Note: even though this view comes with The Events Calendar, you must have PRO installed and activated in order to use it, otherwise the regular WordPress calendar widget will be used. |
| table.php | This file controls the display of the big events calendar. |
Events Calendar PRO
Events Calendar Pro has the following views located in /wp-content/plugins/events-calendar-pro/views:
| File | Description |
|---|---|
| events-advanced-list-load-widget-display.php | This file controls the display for the Events Advanced List Widget. Note: if you have the Pro plugin activated editing the Events Advanced List Widget overrides the Events List Widget included in the base plugin. |
| single-venue.php | This file controls the display of the single venue pages. |
| widget-featured-display.php | This file controls the display of the Next Event Widget. |
Community Events
Community Events has the following views located in /wp-content/plugins/events-community/views:
| File | Description |
|---|---|
| delete.php | This file controls the display for the delete event screen. |
| event-form.php | This file controls the display of the edit and submit event forms. |
| event-meta.php | This file controls the display of custom fields in the edit and submit event forms. |
| event-recurrence.php | This file controls the display of the recurrence options in the edit and submit event forms. |
| events-meta-box.php | This file controls the display of all the event meta (date/time, location, organizer details). |
| my-events.php | This file controls the display of the My Events page. |
| organizer-form.php | This file controls the display of the Organizer meta section in the edit and submit event forms. |
| organizer-meta-box.php | This file controls the display of Organizer select menu on the edit and submit event forms. |
| recurrence-dialog.php | This file controls the display of the Recurrence dialog that appears when editing a recurring event. |
| venue-form.php | This file controls the display of the Venue meta section in the edit and submit event forms. |
| venue-meta-box.php | This file controls the display of the Venue select menu on the edit and submit event forms. |
4. Editing the CSS and JavaScript
CSS
You can add CSS to your theme’s style.css or wherever your theme’s styles are located. As with the template files, you can also override the CSS by creating a folder at /wp-content/themes/your-theme/events/ or /wp-content/themes/your-theme/events/communityand copying the plugins’ CSS files. You’ll find them:
- The Events Calendar (& Pro) CSS:
/wp-content/plugins/events/resources/events.css
- The Community add-on CSS:
/wp-content/plugins/community/resources/tribe-events-community.css
Any CSS in your theme folder will take precedence.
JavaScript
The Events Calendar’s JavaScript is stored at /wp-content/plugins/events/resources/events.js You can add your own JavaScript to your theme’s functions.php file, or to a new JavaScript file located in /wp-content/themes/events/. To do so you need to dequeue the plugin’s loading of this file and enqueue your own. To do this add:
add_action( 'wp_enqueue_scripts', 'example_enqueue_scripts' );
function example_enqueue_scripts() {
wp_dequeue_script( 'tribe-events-calendar-script' );
wp_enqueue_script ('tribe-custom-calendar-script', get_template_directory_uri() .'/events/events.js', array( 'jquery' ), '1.0', true );
}
The above snippet is looking for an events.js file within your /wp-content/themes/mytheme/events/ folder.
Alright sparky, now you should have everything you need to go out and kick some ass. If you need any help be sure to check out our support forums.
