Updating to Version 5

This page is specifically for users upgrading from version 4 to version 5. If you are having issues upgrading, after reading this information, please let us know on the free or pro forums.


IMPORTANT: Before upgrading please back up your database!

Upgrading from version 4 to version 5 is pretty straightforward, and in most cases, all you need to do is follow these simple steps:

  • Upgrade your plugin version as per usual using the automatic updater, or manually updating (http://wp-events-plugin.com/documentation/installation/).
  • When you first update to version 5, the page may take anywhere from a few seconds to a couple of minutes to load, depending on how many events you have and the speed of your server. In the event your page times out during the upgrade, just click reload and installation should proceed from where it left off.
  • Once the upgrade is complete, you will see some notices regarding migration of previous event/location images to your media library. If you would like to import these images to your media library, and attach them to the event and locations, click on the notification, or visit the settings page and see the migration pane at the bottom of this page.
  • If you also have Events Manager Pro, make sure you have version 1.4 or higher.
  • Visit your blog’s permalinks page and resave them (no modifications needed).

That’s it! Events Manager should be ready to go! However, it is important we run through a few checks to make sure it has upgraded correctly.

Check Changes

Whilst every effort has been made to make Events Manager look and work the same way as before, under the hood, it’s a very different plugin which not only should be faster and more robust, but opens up the possibilities for what you can do with your events. It’s important you check a few things to make sure your upgrade went as expected, as well as noting the new changes in the plugin.

New Pages for Lists

Previously, Events Manager required you to select an events page to display all event/location/category information.

Now, this is entirely optional. Single event, location and category pages have WordPress-created links, and you can select individual pages to list events, locations or categories if need be.

When upgrading, you should have three new pages created for you, all being children of your original events page, and mimicking the same URL structure as before:

  • Locations
  • Categories
  • My Bookings

You can now modify the contents of these pages individually, including the title, meta-data (e.g. using an SEO plugin) directly on the WordPress pages themselves.

New Event/Location URLs

If you upgraded from Events Manager 4, your old url structures should remain very similar, although your event and location will change slightly.

IMPORTANT: Please note that code IS in place to redirect old URLs with 301 redirects in order to preserve SEO rankings. Aside from this, you can now customize each event and location with SEO plugins (so hopefully you’ll see an increase in rankings!). Check some old event/location URLs to see that redirections are working correctly for you.

By default, single location and event pages will now have this URL structure.

/oldeventspage/event/event-slug/ > /oldeventspage/event-slug/

/oldeventspage/location/location-slug/ > /locations/location-slug/

Categories should remain unchanged, but you should double check these too. You can edit the permalink structures of all these elements in Events > Settings > Pages > Permalink Slugs of your admin area.

Category ID Changes

This is only relevant to people using shortcodes, PHP code, or widgets to display category specific event information.

Categories are now a WordPress taxonomy, just like categories for posts, but exclusively for events. There are many advantages to do things this way, but one of the only trade-offs for this new update is category ids have changed.

If you have any event information depending on specific category Ids, make sure you look up the new id, which can be located by visiting the categories page, and viewing the link to each category edit page, which contains a bit like tag_ID=123 (where 123 is your id)

Multi Site Users

If you are not using Multi Site, then stop reading here!

Aside from category ids changing, the only other area that may experience some changes is Multi Site global mode.

If you are using Events Manager WITHOUT global tables enabled, you can skip this part.

Network Admin Options

All Network-Specific options should now be found in your network admin panel. Alongside options, you also have an upgrade tool. This is especially useful for large upgrades like from 4 to 5, as often you need to visit the admin panel to get this working (The WordPress network updater does not do it).

More Options

You’ll also notice significantly more options in the Multi Site Options panel when global tables are enabled, which are specifically for controlling how events and locations are handled.

Since Events and Locations are custom posts, if a user creates an event on a sub-blog, the post itself will remain on that blog. If you choose not to link directly to sub-blog events , then a copy of the post will be shown, with a custom url similar to the previous format of Events Manager 4 (e.g. yoursite.com/eventspage/event/slug).

Locations have slightly different options to events in this case. Since some sites may want to host location pages exclusively on the main blog, you can force all locations to be created on your main blog, and sub-blog users will see a different location interface for viewing site-wide events (this is the same form used by front-end/BuddyPress location editing).

Global Categories

Category information is stored in the main blog, associations between posts and categories site-wide are located in the wp_em_meta table.

Developer Notes

A quick overview for developers. If you have made any modifications to template files, or have hooked into Events Manager in any way, it’s important to check that your changes are compatible with version 5.

There have been minimal function name changes, so in many cases your modifications should still work.

There inevitably are some major changes in the objects, specifically the EM_Event, EM_Location and EM_Category objects.

The most notable change that may affect modifications to the plugin is that we are now using the full database table column name for properties, so e.g.

$EM_Event->start_date would now be $EM_Event->event_start_date
$EM_Booking->price is now $EM_Booking->booking_price

If you have named your variables appropriately, this should be a case of some smart search/replace calls on your text editor

EM_Event and EM_Location – How it’s handled

There’ll be more documentation for developers in the coming weeks during the transition.

Events and Locations still use the wp_em_events and _locations tables for storing data, but this is now used as an index for searching events. You’ll notice both objects now have a post_id property, which is how information is loaded into the object.

In both cases, this class sort of (sort of, because there isn’t a Post class in WP) extends the custom post object returned by the usual get_post() function. Extra information such as dates etc. Are stored as custom post fields, with the underscore preceding the name (e.g. _event_start_date).

EM_Category and EM_Categories

Categories are now custom taxonomies.

EM_Categories now uses functions such as get_terms() to retrieve category information about events.

EM_Category now ‘extends’ the $term object returned by get_term(), but keeps the extra functions from before. The property names are now the same as returned by get_term().