WordPress Events List

IMPORTANT: A newer version of this post has been released! The code below doesn’t work over multiple years. Please read: An Updated WordPress Events List instead!

An events list is just what you would expect; a list of upcoming events, ordered by the date they are taking place on (Not the date they were written on!).

In this post, we are going to create our own events list that will let us add events simply by writing posts and assigning them to an “Events” category. It can’t get much easier than that!

This is exactly what we set up for a recent client of ours, American Majority. You can see their full events listing here, or solely the events in one state here (And on both pages, you’ll see the corresponding list in the sidebar as well).

There are a lot of calendar plugins out there, but there are two reasons this method may be better:

  • Full power of WordPress posts behind you, i.e. users can leave comments, and you can embed any kind of media you like in your post, even signup forms.
  • More usable for your readers. They can see event titles and descriptions instantly, and click the ones relevant to them. Calendars normally just show the date events are happening on (Because they have limited space in the sidebar), making you have to click on everything.

A bonus is that it never hurts to have one less plugin!

Where calendars shine is when they occupy a full page (i.e. They have room to give event titles!), and when you run a massive number of events (More than 1 each day, e.g. daily training session times for a golf coach etc.).

Create Some Events

The first thing we will do is to create some event posts for us to display later:

  • Create a new post, and give it whatever title and content you like.
  • Add the post to a new category called “Events” (Can be any name you like, but Events makes sense!)
  • In the custom fields section (Beneath the main content area), create a new custom field with a “Name” of “Date” (Without the quotes), and a “Value” of the date for the event, in the form: mm/dd/yyyy 00:00:00

Events Custom Field

  • Publish the post.

Setting the time is optional, but it would be useful if there are ever two events on the same day.

Build the Query

The great part part of this is that we can do all of the work with WordPress’ query_posts tag, so only relevant posts will be pulled from the database.

Let’s go through making the query, step by step.

1 – Grab Our Events Posts

First of all, let’s just pull in a certain number of posts from the Events category. In this case, we’ll take 5 (A nice number for a sidebar, but you could make it 20 or more in order to make a full events listing page).

<?php query_posts('showposts=5&category_name=events’); ?>

2 – Ensure the Posts Have a Date Set

As well as being in the right category, let’s make sure we’ve remembered to set the date of the event.

<?php query_posts('showposts=20&category_name=events&meta_key=Date); ?>

3 – Don’t Show Any Events Which Are Over

If the event date has already passed, we don’t want to list it anymore. We do this by getting the current date in PHP, and then comparing it with the dates in the posts.

<?php // Get today's date in the right format
$todaysDate = date('m/d/Y H:i:s');
<?php query_posts('showposts=20&category_name=events&meta_key=Date&meta_compare=>=&meta_value=' . $todaysDate); ?>

4 – Order the Events So the Soonest is First

We do this by ordering the posts by their meta_value (i.e. the date), and setting the order mode to lowest first.

<?php // Get today's date in the right format
$todaysDate = date('m/d/Y H:i:s');
<?php query_posts('showposts=20&category_name=events&meta_key=Date&meta_compare=>=&meta_value=' . $todaysDate . '&orderby=meta_value&order=ASC'); ?>

We now have our 5 posts, corresponding the next 5 events in the list.

Display the Events

We can use a regular WordPress loop now to format the posts in any way we like.

Sidebar Events List

For example, the following would display a list of the events with their excerpts beneath.

<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
	<h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
	<p><?php the_excerpt(); ?></p>
<?php endwhile; else: ?>
<li>Sorry, no upcoming events!</li>
<?php endif; ?>
<?php wp_reset_query(); ?>

The last line puts our page query back to normal (i.e. the true content of the page), so we won’t break things further on!

(Optional) Organize Your Events

You may wish to organize your events into different groups. Thankfully, this is very easy to do. We just add a tag!

For example, on American Majority we split the events up by state, and then each state displayed only its own events (And a central page listed all of the events from every state).

State Events Only

Let’s say we tag a state with “Texas”, then on the Texas page, our new query would simply be:

<?php query_posts('showposts=20&category_name=events&meta_key=Date&meta_compare=>=&meta_value=' . $todaysDate . '&orderby=meta_value&order=ASC&tag=texas'); ?>

All Done!

That’s you up and running now! And because we used the WordPress loop, what you can do with the posts is extremely flexible (e.g. Adding thumbnails, or publishing an RSS feed of them), the exact same way you would with any other set of posts.

Have you ever set up an events list before? How did you do it? With a plugin or a different method?

Enjoy this post? You should follow me on Twitter!