Description
The purpose of this plugin is to add an event type similar to the normal post type. By design this plugin doesn’t provide any ready-made layouts, and allows the events to be fully integrated and customized to the theme of your choosing.
Current Features
- Admin pages to view/create/modify events.
- Available data fields for events: start date, end date, venue, category
- Create weekly or biweekly recurring events
- Fully customizable widget for displaying upcoming events.
The custom post type created by the plugin is named ‘am_event’ and has two taxonomies: ‘am_event_categories’ and ‘am_venues’. Dates are stored as post metadata. Displaying the events is done in the theme files using WP_Query and the template tags provided by the plugin. This allows full control over the layout and what elements to show.
The widget for displaying upcoming events uses a simple template system for full control of the layout.
If you think something critical is missing, feel free to send me a request.
The plugin is available in the following languages (pot-file included for additional translations):
- English
- French
- Norwegian
- Finnish
TUTORIAL
For integrating AM Events to an existing theme, I suggest creating a child theme with custom page templates. You can find an example of a working Twenty Twelve child theme from https://github.com/attemoi/am-events-child-theme containing three different page templates for event pages.
Widget
Here are the shortcodes available in the upcoming events widget template.
- [event-title]
- [start-date]
- [end-date]
- [event-venue]
- [event-category]
- [content]
- [thumbnail]
- [excerpt]
- [permalink]
- [meta]
Conditional shortcodes:
- [if cond=”startdate-is-enddate”]
- [if cond=”startdate-not-enddate”]
- [if cond=”startday-is-endday”]
- [if cond=”startday-not-endday”]
- [if cond=”has-venue”]
- [if cond=”has-category”]
The title can be linked to the event post with the ‘link’ attribute, e.g. [event-title link=true]
The category and venue can also be linked similarly to their respective archive pages using the ‘link’ attribute, e.g. [event-category link=true]
The number of words displayed in the title, content or excerpt can be limited by the ‘limit’ attribute, e.g. [content limit=25] or [event-title limit=10].
The dates can be formatted using the ‘format’ attribute, e.g. [start-date format=’d.m.Y H:i’] (see PHP date for formatting options). If no format is given, the default WordPress date format is used.
You can use any shortcode as many times as needed in a single template. To separate date and time of start date for example you could write:
[start-date format='d.m.Y']
<span>divider</span>
[start-date format='H:i']
Example usage of conditional shortcode:
[start-date format='D d.m.Y H:s']
[if cond='startdate-not-enddate']
- [end-date format='D d.m.Y H:s']
[/if]
Template tags
Template tags were introduced in version 1.3.0 and are listed below. More documentation can be found in the source files.
// Template tags for getting and displaying event dates
am_the_startdate($format = 'Y-m-d H:i:s', $before = '', $after = '', $echo = true)
am_get_the_startdate( $format = 'Y-m-d H:i:s', $post = 0 )
am_the_enddate($format = 'Y-m-d H:i:s', $before = '', $after = '', $echo = true)
am_get_the_enddate( $format = 'Y-m-d H:i:s', $post = 0 )
// Template tags for getting and displaying event venues
am_get_the_venue( $id = false )
am_in_venue( $venue, $post = null )
am_get_the_venue_list( $separator = '', $parents='', $post_id = false )
am_the_venue( $separator = '', $parents='', $post_id = false )
// Template tags for getting and displaying event categories
am_get_the_event_category( $id = false )
am_get_the_event_category_list( $separator = '', $parents='', $post_id = false )
am_in_event_category( $eventCategory, $post = null )
am_the_event_category( $separator = '', $parents='', $post_id = false )
Example of displaying the first category of the current event post:
$categoryArray = am_get_the_event_category();
echo $categoryArray[0]->name;<h3>Creating a WP_Query</h3>
The custom post type is named ‘am_event’
The taxonomies are named ‘am_venues’ and ‘am_event_categories’.
The event post has metadata named ‘am_startdate’ and ‘am_enddate’ that are formatted like ‘yyyy-mm-dd hh:mm’
So suppose I wanted to display all events with a category of ‘other’ and venue ‘mcdonalds’. I would then make a WP_Query like this:
$args = array(
'post_type' => 'am_event',
'post_status' => 'publish',
'tax_query' => array(
'relation' => 'AND',
array(
'taxonomy' => 'am_venues',
'field' => 'name',
'terms' => 'mcdonalds',
),
array(
'taxonomy' => 'am_event_categories',
'field' => 'name',
'terms' => 'other'
),
),
);
$the_query = new WP_Query($args);
if ($the_query->have_posts()) {
while ($the_query->have_posts()) {
$the_query->the_post();
$postId = $post->ID;
// Use template tags to get start and end date
$startDate = am_get_the_startdate('Y-m-d H:i:s');
$endDate = am_get_the_enddate('Y-m-d H:i:s');
// Use template tags to get venues and categories in an array
$venues = am_get_the_venue( $postId );
$eventCategories = am_get_the_category( $postId );
// All the other functions used for posts like
// the_title() and the_content() work just like with normal posts.
// ... DISPLAY POST CONTENT HERE ... //
}
}
If you want the events ordered by start date, add the following to $args:
'orderby' => 'meta_value',
'meta_key' => 'am_startdate',
'order' => 'ASC',
If you need to display only upcoming events, add the following meta_query argument to $args:
'meta_query' => array(
array(
'key' => 'am_enddate',
'value' => date('Y-m-d H:i:s', time()),
'compare' => ">",
),
),
The plugin folder also contains a file “examples.php”, which contains an example function for displaying upcoming events in a table.