Templates

Event Organiser uses various template files, located in the template sub-folder of the plug-in’s folder. Usually: ...wp-content/event-organiser/templates/.

Do not make changes to these files. Any changes will be lost when Event Organiser updates. Instead, to customize or over-ride these templates, make a copy of these files in your theme directory and edit these.

Basic Overview

When WordPress is serving up content it needs to now how to display it – and this of course depends on what the content is. Events will, typically, need to be displayed differently to blog posts. Event Organiser therefore provides default templates to display relevant event information.

However, the templates cannot work with all themes. In any case you will probably want to change what information is displayed and where. Event Organiser gives you complete control of this by allowing you to edit the templates. In fact I encourage you to customize these templates to fit better into your theme, suit your needs and get the most out of this plug-in!

Template Files

Template Template file name Role since
Event page single-event.php The template for displaying an event 1.0
Event Information (on event page) event-meta-single-event.php Not part of the template hierarchy. Used to display event information (e.g., is included by `single-event.php`). 1.7
Event archives archive-event.php The template for displaying listings of events. 1.0
Event venue page taxonomy-event-venue.php The template for displaying listings of events at a particular venue. 1.3
Event category pages taxonomy-event-category.php The template for displaying listings of events of some category. 1.0
Event tag pages taxonomy-event-tag.php The template for displaying listings of events of some tag. 1.2
Event list shortcode shortcode-event-list.php Not part of the template hierarchy. Used to display the `[eo_events]` shortcode. 1.7
Event list widget widget-event-list.php Not part of the template hierarchy. Used to display the events list widget. 1.7

How Do I Customise My Templates?

1. Identify the template to edit

If you want to edit an event's page you want single-event.php. If you only want to edit the event's meta information (that appears just before the content on single-event.php by default), you'll want event-meta-single-event.php.

Event archives, including the year, month & day archives are handled by archive-event.php. The table above should help you identify the template you are after.

2. Copy the template(s) into your theme

This is important, as changes to plug-in files are lost when you update. Once the templates are in your theme the plug-in will know to use them rather than the default ones. (They must have the same name!)

3. Edit! Edit! Edit!

You can now freely edit the templates however you wish. Be sure to checkout the function reference for documentation of the functions available to you (for displaying maps, venue information, event categories, dates etc).

If you're editing a template to fit with your theme - I'd suggest using an existing template in your theme as a base or guide for your event template. Feel free to use Event Organiser's default template as a reference to help you.

Developers

Event Organiser intercepts the template at the template_include hook. If an 'appropriate' template has not been found (in either the child or parent theme) it uses the corresponding default templates (unless template handling has been turned off).

'Appropriateness' is determined by the template name (i.e. archive-event.php) and fully respects the template template-hierarchy. For instance, you can use venue and category specific templates in your theme by creating templates of the form: taxonomy-event-venue-{$venue_slug}.php.

Be sure to name the template file correctly, if Event Organiser cannot find an 'event' template file in the theme directory it will use the pug-in defaults. You can prevent this behavior in the plug-in settings (In your WordPress admin: Settings > Event Organiser). If the templates are disabled, WordPress decides what template file to use according to the template hierarchy - of course, in general, these will not display event dates / venues / categories etc.

Allowing Comments

It has be noted that sometimes 'enabling' comments in the plug-in settings is not sufficient to allow visitors to comment on events. The reason is you need to add where you wish the comments to appear in the templates. You should try to mimic how your theme displays comments, and the easiest way is to copy the comments part of your theme's single.php. The theme TwentyEleven, for example, uses <?php comments_template('',true);?> to display comments. See the Codex for more information.

Templates Not Functioning Correctly?

The default templates should function correctly with most themes. If you are experiencing errors, you can do one of two things:

  1. Replace the templates by making your own copy in your theme directory (see above)
  2. Disable the template pages - this means WordPress will decide what template page to use, according to the template hierarchy, but in general this won't display event dates / venues / categories for example, since these templates would be intended for general posts which don't have the corresponding information associated with them.

Why Isn't This A Bug?

The default templates, even if they do work 'as is' with your theme are intended to be replaced by your own themes. Each website has its own needs and rather than trying to pre-empt that or provide an overwhelming 'cockpit' of options to edit the templates, the plug-in provides basic templates which you can easily replace. This gives you the complete freedom to decide what you want to display, where and how.

Unfortunately the default templates can't work with all themes (one size doesn't fit all). This isn't a bug with either the plug-in or the theme.