Recipe: Override a Template

Goal: Replace a bundled PHP template with your own version from a theme or plugin, without modifying the plugin files.

Seams Used

Seam	Type	Purpose
Template override path	Convention	Place your file at {theme}/eventonomy/{template}.php.
evnm_template_part	Filter	Swap the resolved file path programmatically from a plugin.
evnm_template_part_args	Filter	Modify the $view_data passed to any template.

Override Order

Eventonomy resolves templates in this order (first match wins):

1. {child-theme}/eventonomy/{template}.php
2. {parent-theme}/eventonomy/{template}.php
3. {plugin}/templates/{template}.php - the bundled fallback.

Available Templates

File	Renders
single-event.php	The full single-event page layout.
events-list.php	The events archive list wrapper.
event-card.php	A single event card in the list/grid.
rsvp-form.php	The RSVP form.
parts/event-meta.php	Date, time, timezone, and status row.
parts/event-date.php	Date/time formatted block.
parts/organizer.php	Organizer name and link block.

Option 1 - Theme Override

Copy the bundled file from eventonomy/templates/event-card.php into your theme at {your-theme}/eventonomy/event-card.php and edit it.

Eventonomy discovers the override automatically. No PHP required.

Rule: Templates receive a read-only $view_data array prepared by Services. Never run database queries inside a template - add extra data upstream via evnm_rest_prepare_event or a view_data filter, then read it from $view_data.

Option 2 - Plugin Override (Using the Filter)

Use evnm_template_part to swap the path programmatically - useful when you are distributing an add-on plugin:

add_filter( 'evnm_template_part', function ( string $path, string $slug, array $view_data ): string {
    if ( 'event-card' === $slug ) {
        $override = plugin_dir_path( __FILE__ ) . 'templates/event-card.php';
        if ( file_exists( $override ) ) {
            return $override;
        }
    }
    return $path;
}, 10, 3 );

Adding Data to a Template

Inject extra view data through evnm_template_part_args:

add_filter( 'evnm_template_part_args', function ( array $args, string $slug ): array {
    if ( 'event-card' === $slug ) {
        $args['sponsor_logo'] = get_option( 'my_addon_sponsor_logo_url', '' );
    }
    return $args;
}, 10, 2 );

Inside event-card.php, read it as $view_data['sponsor_logo'].

Verify It Worked

1. Visit any page that renders the template you overrode (e.g. the events archive for event-card.php).
2. Confirm your markup appears instead of the bundled markup.
3. Check that no database queries run inside your template: install Query Monitor and watch the queries panel while the page loads.

Related

• docs/EXTENDING.md §7 - full template override specification and $view_data shape.
• Architecture - the seven-layer model and where templates sit.
• Recipes Index