=== AM Events ===
Contributors: Moisture
Tags: events, upcoming events, event list, custom post type, custom taxonomy, plugin, widget
Requires at least: 3.3.1
Tested up to: 3.6
Stable tag: 1.3.1
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Adds an event post type with an interface and template tags similar to normal posts.

== Description ==

The plugin adds a custom event post type with two taxonomies: event category and venue. 

Allows the user to add new events just like normal posts with added fields for start time, end time, category and venue. You can also easily create weekly or biweekly recurring events.

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.

As an extra feature, the plugin also includes a widget for showing upcoming events. It uses a very simple template system for full control of the layout.

The plugin is fully translatable. The only available languages at the moment are english(default) and finnish. The download includes a .pot-file for additional translations.

For integrating AM Events to an existing theme, I suggest creating a [child theme](http://codex.wordpress.org/Child_Themes) with custom page templates. You can download a full example of a working Twenty Twelve child theme from my website [(Download link)](http://attemoisio.fi/projects/am-events/twentytwelve-child.zip). It contains three different page templates for events pages.

See Other Notes for detailed information and a small tutorial about the custom post type and the widget.

If you think something critical is missing, feel free to send me a request. I'm using this on some of my client's sites so I'll certainly be improving/fixing it for upcoming Wordpress versions.

== Installation ==

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

== Frequently Asked Questions ==

= Can you give me an example of using WP_Query? =

See 'Other Notes' for a simple tutorial.

== Screenshots ==

1. Widget administration.
2. Creating an event

== Changelog ==

= 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

== Upgrade Notice ==

= 1.3.1 =
* Fixes minor bugs in template tags

= 1.3.0 =
* Adds template tags for getting/displaying event data

= 1.2.1 =
* Fixes localization typos
* Adds simple WP_Query tutorial to readme.txt

= 1.2.0 =
* Adds support for php 5.2 (previously needed 5.3)
* Fixes bugs.

= 1.1.0 =
* Adds localization support for date format.

= 1.0.1 =
* Fixes bugs in the upcoming events -widget

== Widget ==

Here are all the tags that can be used in the upcoming events widget template. Don't add any extra spaces inside the brackets.

 * {{title}}
 * {{event_category}}
 * {{venue}}
 * {{start_day_name}}
 * {{start_date}} 
 * {{start_time}}
 * {{end_day_name}}
 * {{end_date}}
 * {{end_time}}
 * {{content}}

= 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 )

== Creating a WP_Query ==

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.