Skip to content

The Events Calendar

Jump to: Methods

Template Overrides

The Events Calendar Template Files - Knowledgebase

Customizing Template Files - Knowledgebase

Files needed in Theme

Context Providers

  • app/Providers/TemplateContext/ArchiveTribeEvents.php
  • app/Providers/TemplateContext/SingleTribeEvents.php

Models

  • app/Models/Posts/TribeEvents.php

Hooks

  • app/Hooks/TheEventsCalendar.php

Views

  • resources/views/pages/archive-tribe_events.twig
  • resources/views/pages/single-tribe_events.twig

Blocks

  • blocks/EventExcerpt

Template Overrides

  • tribe/events/single-event-blocks.php

Usage

The events calendar has been ported for ease of use by leveraging the timber post classmap. This allows for easy access to the events calendar data in the twig templates.

When retrieving the events calendar posts using the tribe event functions, the data needs to be converted to a timber post object.

<?php
$events = tribe_get_events([
            'posts_per_page' => -1,
            'start_date' => 'now',
            'featured' => true,
        ]);
/**
 * A note about the following
 * if Timber::get_posts is called on an empty array
 * it will get the page data of the current page
 * this is why we check if the array is empty
 */
if (empty($events)) {
    return [];
}
$events =  Timber::get_posts($events);
//$events is now using the TribeEvents model

TheEventsCalendar Hook

Inside of the hook we are specifying the blocks that should be included, these blocks are primarily there as input forms for the user.

It is important that we reference the design and project requirements, if the design doesn't have certain elements, we should remove them here.

For example, if the design doesn't utilize the maps block, we should remove it from the template.

In addition to the blocks, we are also specifying the template structure. This is the structure that the block editor will use to render the event data.

The group blocks currently need to remain in the structure. It is possible that the data could be extracted by refactoring the core parsing to use pars_blocks, but this is not currently implemented.

The wrapper blocks (group blocks) are also used to differentiate the data in the block editor. Ideally, we would have a more robust way of doing this, but this is the current implementation. Ideas are welcome...

Once again, do not remove the group blocks. 

<?php
namespace Origins\Hooks;

use Og\Traits\Actions;
use Og\Traits\Filters;
use Og\Interfaces\ActionInterface;
use Og\Interfaces\FilterInterface;

class TheEventsCalendar implements ActionInterface, FilterInterface
{
    use Actions, Filters;

    public function should_load(): bool
    {
        $plugin_is_active = is_plugin_active('the-events-calendar/the-events-calendar.php');
        $is_admin = is_admin();
        return $plugin_is_active && $is_admin;
    }
    public function load(): void
    {
        /**
         * see https://theeventscalendar.com/knowledgebase/change-the-default-event-template-in-block-editor/
         */
        $this->add_filter('tribe_events_editor_default_template', function ($template) {
            $template = [
                [
                    'core/group',
                    [
                        'templateLock' => 'all',
                        'anchor' => 'EventWrapper',
                        'className' => 'bg-gray-950/10 p-4 rounded-lg before:content-["Event_Details"] before:leading-loose before:text-2xl before:font-bold before:mb-4',
                    ],
                    [
                        ['tribe/event-datetime'],
                        ['core/post-featured-image'],
                        ['tribe/event-organizer'],
                        ['tribe/event-venue'],
                        ['tribe/event-website'],
                        ['tribe/event-links'],
                        [
                            'core/group',
                            [
                                'anchor' => 'EventExcerpt',
                                'allowedBlocks' => ['core/paragraph'],
                                'className' => 'before:content-["Event_Excerpt"] before:text-2xl before:font-bold mt-5 befor:leading-loose',
                            ],
                            [
                                ['og/event-excerpt'],
                            ],
                        ]
                    ],
                ],
            ];
            return $template;
        }, 11, 1);
    }
}

Template Context

ArchiveTribeEvents.php

This is the default all events page from TEC /events.

The tribe_content is the same as what the events calendar would create if the plugin was used in a standard way. 

<?php

namespace Origins\Providers\TemplateContext;

use Tribe\Events\Views\V2\Template_Bootstrap;

class ArchiveTribeEvents extends Base
{
    public function load()
    {
        return [
            'tribe_content' => tribe(
                Template_Bootstrap::class,
            )->get_view_html(),
        ];
    }
}

SingleTribeEvents.php

This is the single event page from TEC /events/{event}. All that is added here is the link to the events page and the labels for the events. These are pulled from the TEC settings. 

<?php
namespace Origins\Providers\TemplateContext;


class SingleTribeEvents extends Base
{
    public function load()
    {
        return [
            'TEC' => [
                'link' => esc_url(tribe_get_events_link()),
                'label' => [
                    'plural' => tribe_get_event_label_plural(),
                    'singular' => tribe_get_event_label_singular(),
                ]
            ]
        ];
    }
}

Models

TribeEvents.php

This is the core of the Events Calendar integration.

These would be accessed in twig or php like so: 

{{ post.event_content }}

<?php
$post->event_content

Methods

The following methods are available on the model:

event_content - The content of the event

event_excerpt - The excerpt of the event, pulled from the EventExcerpt Block contents. excerpt is still available from the post object.

start_date() - The start date of the event. This can receive a format string as an argument. See php date

end_date() - The end date of the event. This can receive a format string as an argument. See php date start_time() - The start time of the event. This can receive a format string as an argument. See php date

end_time() - The end time of the event. This can receive a format string as an argument. See php date

is_all_day - A boolean value that is true if the event is all day.

is_same_day - A boolean value that is true if the event starts and ends on the same day.

timezone - The timezone of the event.

seperator - an array containing the seperator for the date and time. This is set in the TEC settings globally, but also the seperator can be set per event. 

// example output
<?php
[
    'date' => ' - ',
    'time' => ' - ',
]

venue - array of venue details. 

<?php
[
    'name' => tribe_get_venue($this->ID),
    'address' => tribe_get_address($this->ID),
    'city' => tribe_get_city($this->ID),
    'state' => tribe_get_region($this->ID),
    'zip' => tribe_get_zip($this->ID),
    'country' => tribe_get_country($this->ID),
    'phone' => tribe_get_phone($this->ID),
    'website' => tribe_get_venue_website_url($this->ID),
    'map' => tribe_get_map_link($this->ID),
];
organizer - array of organizer details. 
<?php
[
  'name' => tribe_get_organizer($this->ID),
  'phone' => tribe_get_organizer_phone($this->ID),
  'email' => tribe_get_organizer_email($this->ID),
  'website' => tribe_get_organizer_website_url($this->ID),
]
event_map - iframe html to generate gmap based on the venue.

is_recurring - boolean value that is true if the event is recurring.

sharing_links - the TEC sharing links to add to the various calendar types. HTML is returned.

event_website - the event website url.

event_website_button - array of data for the website button from the editor. 

<?php
[
    'label' => 'Sign Up',
    'url' => 'https://www.google.com',
    'target' => '_blank',
]
recurrence_data - array of recurrence metadata. 
<?php
[
    'description' => 'Recurring Event',
    // 'icon' => this references an svg from TEC
    // 'link' => link to all the recurring events
]
Buggy methods:

tec_next - the next event, seems to not be working correctly. (tribe_get_next_event_link)

tec_prev - the previous event, seems to not be working correctly.(tribe_get_prev_event_link)

All typical post methods are available as well.

DateTime Twig Template Logic

The tribe classes aren't needed here, this is just a direct port from TEC default template. 

<p>
  <!-- Always have the start date -->
  <span class="tribe-events-schedule__date tribe-events-schedule__date--start">
    {{post.start_date()}}
  </span>

  {% if not post.is_all_day %}

    <!-- Not an all day event, lets put the time -->
    <span class="tribe-events-schedule__separator tribe-events-schedule__separator--date">
        {{post.seperator.date}}
    </span>
    <span class="tribe-events-schedule__time tribe-events-schedule__time--start">
        {{post.start_time()}}
    </span>


    <!-- starts and ends on same day -->
  {% elseif post.is_same_day %}
    <span class="tribe-events-schedule__all-day">
        All Day
    </span>
  {% endif %}

    <!-- if the event has a different start and end date and time -->
  {% if not post.is_same_start_end %}

    {% if not
                post.is_all_day or not post.is_same_day %}
        <span class="tribe-events-schedule__separator tribe-events-schedule__separator--time">
            {{post.seperator.time}}
        </span>
    {% endif %}



    {% if not post.is_same_day %}
        <span class="tribe-events-schedule__date tribe-events-schedule__date--end">
            {{post.end_date()}}
        </span>


        {% if not post.is_all_day %}
            <span class="tribe-events-schedule__separator tribe-events-schedule__separator--date">
                {{post.seperator.date}}
            </span>
            <span class="tribe-events-schedule__time tribe-events-schedule__time--end">
                {{post.end_time()}}
            </span>
        {% endif %}


    {% elseif not post.is_all_day %}
        <span class="tribe-events-schedule__time tribe-events-schedule__time--end">
            {{post.end_time()}}
        </span>
    {% endif %}


    {% if post.show_time_zone %}
        <span class="tribe-events-schedule__timezone">
            {{post.timezone}}
        </span>
    {% endif %}


  {% endif %}

Modifying TEC Templates

There may come a time when you need to modify the TEC templates. To do this, we can either port that section over to Twig and then render it accordingly or just modify the PHP template directly.

If you modify the PHP template directly and need access to a method on the model that isn't available otherwise, you can use the following code to get the model.

<?php
// Typically there is an $event variable available in the template. This is a WP_Post Object. To convert it to the model and become a Timber Post Object, we simply pass it to the Timber::get_post method.

$event = Timber::get_post($event);

// Now we can access the methods on the model.
$event->start_date();

Here is an example of modifying the list view of the events calendar to use our event excerpt available on the model.

<?php
//File: tribe/events/v2/list/event/description.php

<?php
/**
 * View: List Single Event Description
 *
 * Override this template in your own theme by creating a file at:
 * [your-theme]/tribe/events/v2/list/event/description.php
 *
 * See more documentation about our views templating system.
 *
 * @link http://evnt.is/1aiy
 *
 * @version 5.0.0
 *
 * @var WP_Post $event The event post object with properties added by the `tribe_get_event` function.
 *
 * @see tribe_get_event() For the format of the event object.
 */
$event = \Timber\Timber::get_post( $event ); //new line
if ( empty( (string) $event->excerpt ) ) {
    return;
}
?>
<div class="tribe-events-calendar-list__event-description tribe-common-b2 tribe-common-a11y-hidden">
    <!-- old: <?php echo (string) $event->excerpt; ?> -->
    <!-- new: <?php echo (string) $event->event_excerpt; ?> -->
</div>