AM Events Plugin

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.

This section describes how to install the plugin and get it working.

1. Upload folder am-events to the /wp-content/plugins/ directory
2. Activate the plugin through the ‘Plugins’ menu in WordPress

1. 

   Creating an event

2. 

   Widget administration

3. 

   Example page with events and the widget.

4. 

1.13.1

• Fix PHP debug error on some admin pages

1.13.0

• Replace jQuery datetimepicker with flatpickr

1.12.0

• Updated jQuery UI date/time picker

1.11.0

• Added new conditional shortcodes for venues and categories

1.10.0

• Added hooks for including extra fields to event posts
• Added [meta] shortcode for widget

1.9.8

• Fixed problem with tags

1.9.7

• Fixed admin panel event list ordering

1.9.6

• Fixed tags being stripped from recurring events

1.9.5

• Fixed compatibility with WordPress 4.3

1.9.4

• Fixed date localization issues

1.9.3

• Fixed widget category and venue filtering bug

1.9.2

• Translation fixes.
• Added thumbnail shortcode to widget

1.9.1

• Fixed bug when removing event categories from recurring events

1.9.0

• Improved handling of recurring events
• Added start and end dates to quick edit

1.8.0

• Added conditional tags for the widget

1.7.1

• Added French language

1.7.0

• Added option to change slug for event posts
• Added [excerpt] shortcode for the widget
• Added customizable “No upcoming events” message to widget
• Added option to change how long passed events are shown in the widget

1.6.0

• Added option to change time picker minute step
• Fixed featured image and excerpts not copying when creating recurrent events

1.5.1

• Fixed a few minor bugs

1.5.0

• Added support for thumbnail and excerpt for event posts

1.4.0

• Added new improved widget template shortcode system

1.3.1

• Fixed minor bugs in template tags

1.3.0

• Added template tags for getting and displaying event data

1.2.1

• Fixed localization typos
• Added simple WP_Query tutorial in ‘Other Notes’

1.2.0

• Added support for PHP 5.2 (previously needed 5.3)
• Fixed multiple bugs

1.1.0

• Added localization to date format

1.0.1

• Fixed bugs in the upcoming events -widget
• Added missing examples.php

1.0.0

• First released/stable version