AM Events

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.