Knowledgebase | The Events Calendar

Using Template Filters and Actions

Within our templating system introduced in version 5.0 of The Events Calendar, we created multiple entry points for theme designers and plugin developers to inject and/or modify the contents of the default views.

In this article, we will go over the process of including a new theme template file into the default List View as well as including a template file directly from another plugin.

Including the author of an event

We will use the tribe_template_before_include:$template action to include the author of our event below the title and above the venue information.

Include the author of an event with a template filter

The title of the event triggers the tribe_template_before_include:events/v2/list/event/venue action, which we will use to include an extra template file from your theme. Let us start by creating the following file in your theme folder: tribe/events/v2/list/event-author.php.

Let’s add this in there:

<div class="tribe-common-b2">
 Author: <?php the_author(); ?>
</div>

Next, we need to include the following code into your functions.php, so that that new file can be included properly:

<?php
add_action(
  'tribe_template_before_include:events/v2/list/event/venue',
  function ( $file, $name, $template ) {
    $template->template( 'list/event-author' );
  },
  10,
  3
);

The result will be:

The result using a template filter

On version 5.0 our event templates are set up to work with the WordPress default Post functions, we wanted all developers to feel at home when creating customizations to our event views.

Mark events happening on Christmas day

In this example, we will use another template action to include some emojis after the date if the event happens on either the 24th or 25th of December.

Like the author example above, you can create the following file in your theme root folder tribe/events/v2/list/christmas-marker.php

<?php
// Fetch the event details for the current event.
$event = tribe_get_event( get_the_ID() );
$christmas_days = [ '12-24', '12-25', ];

// Don’t print anything when it is not Christmas.
if ( ! in_array(
    $event->dates->start->format( 'm-d' ),
    $christmas_days,
    true
) ) {
  return;
}
?>

<span>
 ???
</span>

Once you are done with that, we need to make sure to include that newly created file in the correct place, by adding an action to tribe_template_after_include:events/v2/list/event/date/meta.

<?php
add_action( 'tribe_template_after_include:events/v2/list/event/date/meta', function ( $file, $name, $template ) {
 $template->template( 'list/christmas-marker' );
}, 10, 3 );

With the above code in place, we will be able to see the new emojis on December 24th and 25th!

Add emojis with template filters and actions

In this example, we made use of the tribe_get_event() function, which returns a WP_Post similar to get_post() from WordPress. The primary difference is that this tribe_get_event() function has been tailored to include more Event-specific information.

As you can see, the $events->dates->start property stored on that object contains an instance of the PHP DateTimeImmutable object, giving you access to any DateTimeImmutable methods. Using format_i18n(), dates that have translation will be translated.

Prevent a specific part of the view from appearing

Now, we will move into an example that involves removing content from the screen instead of adding it.

In the previous versions of our code before version 5.0 it meant that you would need to use some CSS to hide an element from the site visitor.

With our updated views, we implemented ways for you to be able to short-circuit the rendering of any template loaded.

Adding the following code into your functions.php file will remove the venue part of the events in the day view only.

add_filter( 'tribe_template_pre_html:events/v2/day/event/venue', '__return_false' );

Note that we made use of the method __return_false which is a default WordPress method that will always return a boolean false, which prevents the template from being generated, which improves performance compared to generating the HTML and then using CSS to hide it.

In this case, the prefix for our hook is tribe_template_pre_html: which is a filter that happens before we start generating the HTML for the file. 

Keep in mind that WordPress filters will always require some value to be returned whereas actions like the two examples, above, will not, just printing the value on the screen will do the job.

Hooks available in our templates

All of the view files included by The Events Calendar and its add-ons from version 5.0+ are using the Tribe__Template PHP class, which will handle the process of locating the files; passing context variables to those PHP files and returning the HTML after all the required actions and filters are triggered, to allow for customization.

The template method will trigger and apply a number of actions and filters each time a template load is triggered.

Besides the hooks used above, there are a couple of others in the codebase. Below, you will find links to our documentation explaining a little bit more about how they work.

Filters available

Actions available