The Events plugin creates a new post type in WordPress to handle events – posts which have a start and end date – and display them in an order dictated by these dates. It is essentially a WordPress Post which has its own taxonomies (categories and tags), and is ordered in a different way.
In addition, the plugin can output calendars and feeds in different formats (RSS, JSON, iCAL), and creates its own permalink structure to enable the display of events using dates in the URL.
Creating a new event
This is done in the same way as you would create a new post, with the addition of setting dates for the event.
On the post edit screen, you will see a box on the right (or below the editor, depending on your screen display preferences) with some inputs for a start date / time and an end date / time. Clicking in these inputs will display a date / time picker to help you input dates in the correct format.
Once you have added a start date / time, you can check a box to indicate that the event takes place for the whole day (checking this will hide the date controls for duration and finish), or select a duration from a drop-down list to automatically input the end date / time. You can also input the end date / time for the event manually using the same method as you used for the start date / time.
You can also mark the event as “sticky” – this will put the event at the top of the events listing on the events archive page (if you have set the display of sticky events in the plugin options). This enables you to promote events which may be taking place far into the future, and may only make it onto the events archive page shortly before they take place – depending on the frequency of the events you are promoting.
The remaining field is for a URL of an external site where the details of the event are published. If this is filled in, links to the event from the events archive page, or from listings generated by the widget or shortcode, will point to the external URL.
For some output formats, the content or excerpt for the post is displayed in the listings, so ensure you have filled out these fields if you are using these output formats.
Events formatting
The options in the plugin to control the formatting of events should suit the majority of user needs. If you want to change the HTML output for events and have mnore control over their display, you can do this in a number of different ways:
Customising templates
The plugin utilises two different templates for display of an archive page and a single event, called archive-event.php and single-event.php respectively. If you copy these templates from the plugin directory to your theme directory, the plugin will use the templates in your theme instead, allowing you to change the formatting to whatever suits your needs.
Using filters
Some of the output from the plugin is handled internally, so can only be changed by using filters. The following filters are available:
- event-format
- This filter is used to format the output of a single event in a listing generated by the shortcode or widget. A filter function will be passed a post object as its only argument, and its output is expected to be returned (not printed) as formatted as HTML. The post object also contains the event meta fields in a meta property, with the following values:
$post->meta["event_start"]– the start date of the event, expressed as a UNIX timestamp.$post->meta["event_end"]– the end date of the event, expressed as a UNIX timestamp.$post->meta["event_allday"]– a boolean (true / false) value indicating whether it is an all day event.$post->meta["event_is_sticky"]-a boolean (true / false) value indicating whether it is a sticky event.$post->meta["event_url"]– the URL for the event.
- event-date-format
- This filter is used to format dates. The filter function will be passed and array containing the following members:
start– the start date of the event, expressed as a UNIX timestamp.end– the end date of the event, expressed as a UNIX timestamp.allday– a boolean (true / false) value indicating whether it is an all day event.
- event-search-bar
- This filter can be used to change the appearance of the search bar. The filter function will be passed the finished output from the plugin.
Plugin Options
Options for the plugin are split into three sections, one which contains the settings for the plugin which govern the way it integrates with the site, one to set the display options for event archive pages, and one to set the format of dates shown by the plugin.
THe main plugin options include some very important settings which govern the URL structure used by the plugin – what slug will be used in the site’s URL for the post type, and what keywords are used for event categories and tags. There is also a setting for the slug used to display pages of future events, which are handled outside the regular WordPress paging mechanism.
There is also an option here to exclude the javascript and css used for the display of the events calendar and events list. This is provided so you can include the script and CSS in your theme if you wish – note however that the script is dependent on the JQuery library to work.
Event Archive Options
These options control the display of event archive pages. The archive page will, by default, list upcoming events in date order, with the next event at the top of the list and other future events in chronological order underneath. The order of events is reversed for past events, with the most recent displayed first and older events displayed in reverse chronological order after it (like regular blog posts).
The event archive pages do not exist in the sense of regular pages and posts in the WordPress system, so there are two settings here where you can set the title of the archive page, and include some content above the events listing.
All archive pages can include a search bar with a search input (allowing a search within Events), and tools to filter events by category or tag. They can also include a calendar (note that the calendar will always display the current month, no matter what archive page it is displayed on).
The other options for archives govern the number of events which are displayed on the main archive page and other archive pages (past and future). The main archive page can also include a set number of “sticky” events which can be set here.
Event Date Options
The options for date display include settings for date and time formats, date and time labels, and separators between them. The options form will show a preview of the date and time formatted according to your settings.
Shortcode
Shortcodes in WordPress are used to simplify adding complex markup to pages to embed things like video, audio, scripts and image galleries. To use the events shortcode, you type the events keyword in square brackets in the content of your post/page wherever you want the events listing or calendar to appear. The shortcode can also hold additional information, or options, in a series of name/value pairs, e.g.
[events option1="value1" option2="value2"]
Options
format
optional (default “title”) Can be one of the following:
- calendar
- This will display a calendar on the page. You can also set a filter when you select this option to show posts only from certain categories, tagged with certain tags, or taking place between certain dates.
- title
- Each event is listed in an unordered HTML list by the title, linked to the URL for the corresponding event. The date appears under the title (using a line break).
- title_excerpt
- Each event is listed in an unordered HTML list by the title, linked to the page for the corresponding event. The date appears in a paragraph under the title, and the excerpt for the event is included under the date.
- title_excerpt_thumbnail
- Each event is listed in an unordered HTML list using the title and post thumbnail (featured image) which are linked to the URL for the event. This is followed by the date and the excerpt.
- title_content
- Each event is listed in an unordered HTML list by the title, linked to the page for the corresponding event. The date appears in a paragraph under the title, and the full content for the event is included under the date.
- title_content_thumbnail
- Each event is listed in an unordered HTML list using the title and post thumbnail (featured image) which are linked to the URL for the event. This is followed by the date and the full content.
preset
Use this option to display events according to one of the following presets:
- calendar
- This performs the same function as the calendar format option above.
- list_with_calendar
- This outputs a list of events with a calendar.
- list
- This outputs events as a list (the default behaviour).
category_filter
This will filter the events to be displayed by event category. Use event category “slugs” here separated by commas.
tag_filter
This will filter the events to be displayed by event tag. Use event tag “slugs” here separated by commas.
start
Use this to specify a start date / time for events. Only those events whose end date / time occur after this date will be included (use dates in the format dd/mm/yyyy hh:mm:ss).
end
Use this to specify an end date / time for events. Only those events whose start date / time occur before this date will be included (use dates in the format dd/mm/yyyy hh:mm:ss).
thumbnail_size
This controls the size of the thumbnail used in a list of events when the format setting includes it. It can be set to a standard WordPress thumbnail size, a custom image size defined by add_image_size() in the theme, or a custom size (like 200×100 for example).
prioritise_sticky
This setting controls whether “sticky” events are prioritised (i.e. moved to the top) of an events list generated by the shortcode.
num
This setting will limit the number of events shown in the list.
Widgets
The Events plugin comes with a widget which you can use in your sidebars to display a calendar, list events, or both. Each widget allows you to set different options.
Options
Widget options are the same as the options which can be used in the shortcode – see above for an explanation of what these options accomplish.