The Events Calendar v2 Template Reset & Customization Guide

Version: 2.1.0! Changelog

Introduction

The Events Calendar (TEC) is a very powerful WordPress plugin for managing events. However, the way its templates and CSS are implemented—especially the v2 templates—leave much to be desired.

This repository contains useful reset files and a checklist of changes I make on nearly every project that uses The Events Calendar. I wish it weren't so long!

Who Made This?

I'm Mark Root-Wiley of MRW Web Design. I build WordPress websites for nonprofits. Checkout my free resource site Nonprofit WP and my free plugins.

If this saves you an hour and a bunch of frustration, consider buying me a coffee or a beer to say thanks! 🍻☕

Customizations Checklist

Styles

There are two complimentary stylesheets so that TEC inherits and uses more theme styles. This is especially powerful if you are using /theme.json to set colors, font sizes, and a spacing scale.

Use css/tec-remap-custom-properties.scss to override a number of TEC defaults with WP/theme.json defaults
- Follow instructions in file header to review styles, customize additional properties, and delete what you won't be using
Use css/tec-inherit-values.scss reset stylesheet below to get rid of numerous hard-coded values and inherit more theme styles
- Optionally set CSS properties to match theme font sizes and colors
Add custom styles to blocks.
- (Optional) Reference list of useful TEC styling selectors as starting point (slightly outdated as of August 28, 2023).

Template Overrides

TEC provides a powerful system to override various plugin templates like the page-level templates all the way down to a specific block. Most sites will need to customize multiple templates for best results.

Copy and customize /tribe/events/v2/default-template.php into /{theme}/tribe/events/v2/
Clean up one or both single event templates:
- Classic Editor Events: /{theme}/tribe-events/single-event.php
- Block Editor Events: /{theme}/tribe/events/single-event-blocks.php
Customize additional templates as needed. Recommended accessibility fixes to templates:
- /{theme}/tribe/events/v2/list/event.php - Datetime should follow the event's title heading for logical structure
- /{theme}/tribe/events/v2/latest-past/event.php - Datetime should follow the event's title heading for logical structure
- /{theme}/tribe/events/blocks/event-datetime.php - Don't use a Heading 2 for logical heading structure on single events
- /{theme}/tribe/events/v2/list/event/feature-image.php - Apply aria-hidden="true" to featured image link since it's redundant with the event title link in list view

Optional Plugins

Fix a few things about event pages and set a custom default block template with mu-plugin in mu-plugins/tec-customizations.php in this repository
- Customize the default block for a new Event with the tribe_events_editor_default_template filter. See /example-block-templates/ for examples of block templates of various complexity
Install Post Type Archive Descriptions for an editable area at the top of the main events page
Explore additional TEC extensions for customizations (e.g., hide past events, "tweaks" plugin, etc.)

Useful v2 Design Filters

In TEC v2 templates, you can use the tribe_template_pre_html filter to hide specific template parts. For example, to hide the "Read More" links in list views:

/* Hide "Read More" links */
add_filter( 'tribe_template_pre_html:events/v2/components/read-more', '__return_false' );

You can also helpfully add content before or after any template part using tribe_template_before_include and tribe_template_after_include. For example:

/* Add "Hello World" after the "Views" selector in the event bar */
add_action( 'tribe_template_before_include:events/v2/components/events-bar/views', function( $file, $name, $template ) {
  echo 'Hello World';
}, 10, 3 );

References

Changelog

2.1.0 (October 5, 2023)

Better defaults and cleaner styles for Datetime, Price, Venue, and Organizer blocks
Style notices with existing TEC custom properties that aren't used for some reason
Remove SASS nesting so this can be used as plain CSS if desired
Remove post_tag taxonomy from events and don't know tribe_events posts in Tag archives
Add new custom properties in attempt to prevent "flash of TEC blue" links and buttons
Change the organizer link text to the organizer's name
Ensure Subscribe button menu appears above other stuff

2.0.2 (June 7, 2023)

New function in mu-plugin to replace wrapping section with a div for better semantics
Move custom properties in _tec-inherit-values.css to the body instead of :root so they have access to theme.json values set on body
Make sure the datetime block children inherit font-size from the body (or block parent)
Replace hard-coded namespace with __NAMESPACE__ to avoid problem when changing namespace
Hide top border and padding above venue blog and event paging
Remove checklist item for old default-template.php file that is no longer included in the plugin

2.0.1 (May 18, 2023)

This is now a git repository rather than a gist!
Rename css files for clarity
Provide fallbacks for custom properties in tec-inherit-values.css
Split examples into separate files in new examples folder
Add CONTRIBUTING.md

2.0.0 (May 02, 2023)

Added new _tec-reset-variables.scss file for better style reset coverage and more stuff working "out of the box".
Removed some rules from _tec-reset-styles.scss that are no longer necessary due to new custom property definitions.
Add some more useful snippets to the mu-plugin (hide recent past events, show past events in reverse chronological order)
Add absolute position to export events drop-down so it doesn't reflow the page
Add \MRW\TEC\is_tribe_view() function to detect when a TEC page is active (great for enqueueing custom styles!)
Fix: Put mobile-specific styles for event datetime into media query
Remove some dead highlighting styles
Remove snippet to add post type archive description and just recommend Post Type Archive Descriptions plugin more obviously
Remove link to "Remove Export Links" TEC add-on which is no longer available. Add link to extensions page instead
Remove some recommended accessibility template fixes that have been integrated into the plugin!

1.5.0 (August 05, 2022)

Remove font-family now that there's a customizer setting for it

1.4.2 (May 03, 2022)

Attempt to improve subscribe button style overrides dealing with weird focus and hover behaviors. Absolute position dropdown to avoid layout jank

1.4.1 (February 9, 2022)

Improvements to subscribe button overrides to make them more likely to win over unwanted theme styles

1.4.0 (January 19, 2022)

Fix featured event styles in month view
Add styles to override subscribe button styles
New suggestion to hide featured image from assistive technology in list views
Add equivalent template changes to /latest-past/ templates to match /list/ changes where applicable

1.3.0 (August 23, 2021)

Add new selectors for heading styles and links on the new single event templates to match other override styles (fonts, underlining behavior, etc.)
Increase specificity of .tribe-common-c-btn selectors in order to override messed up settings in plugin and ensure the search bar button is the correct color
Remove filter that hid the back link on the single template. Does not work in v2 single events.

1.2.0 (June 18, 2021)

Add new selectors to inherit font styles from the theme
Add editor selectors to try to style blocks closer to front-end. Results will vary.
Bug fix for TEC 5.7.0 template_include filter

1.1.0 (April 20, 2021)

Add /v2/ to path of tribe_template_before_include filter to fix bug in TEC 5.5.
Remove errant SASS variable in style resets
Fix missing accent customization for Featured Styles in list view. Adds new --tec-accent-color variable that defaults to --tec-link-color

mrwweb/the-events-calendar-reset