Creating an Events Manager Add-On : A Complete Walkthrough
Warning: This series of tutorials was designed to help developers and designers learn how to make common modifications and understand some of the possibilities in Events Manager. We assume here that you already know your way around WordPress and some basic knowledge of PHP.
Aside from being the most flexible events plugin for styling without modifying code, Events Manager is made with developers in mind, meaning that any aspect of the plugin can be hooked into and modified to suit your needs!
We have put together a collection of tutorials that create one comprehensive add-on (or plugin) for Events Manager. In this series we will show you how to make a fully fledged plugin that adds further functionality in various aspects of EM.
We hope that you’ll find this useful when you need to make changes to EM without hacking the plugin directly. Or if you’re browsing for flexible event registration plugins on wordpress, maybe this will help!
In this sample project, we are going to add a new plugin called “Styles”, which will allow users to assign certain styles to an Event via a drop-down menu. This functionality effectively gives you the same as event categories, but serves as a great way to show how easy it is to connect to all aspects of this plugin.
Important: Since the release of version 5, you are able to quickly acheive a very similar effect by registering a custom taxonomy with register_taxonomy() and assigning it to the EM_POST_TYPE_EVENT constant.
In this tutorial, you will learn how to do the following:
- Decide where to correctly add your code in an upgrade-safe way
- Create a new custom admin page in events manager for users to manage styles
- Attach custom style information to the event upon instantiation so it can be accessed easily
- Add a meta box in the edit events page for users to select the event style
- Perform necessary actions to save event styles when an event is added or updated
- Make styles searchable via shortcode, and function search attributes
- Insert a style search drop-down menu into the events search form
- Add a custom placeholder for listing the event styles
- Add a custom condition placeholder for showing event information if it has a specific style
- Create a new style pages that lists all events categorized by style (much like the new categories pages)
- Create a new permalink rule so that our new style pages have pretty SEO permalinks.
This may sound like a lot, but surprisingly, this can be done comfortably in less than 300 lines of code! However, due to the length of the explanation, and the modularity of these functions, we’ll be splitting this tutorial up into various steps, as each step can be reused in various ways to tweak and modify Events Manager to your liking.
Step 1 – Adding your code to the right files
We need to decide where to make these changes. In this case, we’re just going to create an em-styles.php file within our mu-plugins folder and insert the code there. Here’s some more information on how to add php code to wordpress.
Step 2 – Create a new custom admin page in Events Manager
Users will need to be able to manage styles, so we have to create a styles admin page that allows users to add, edit and delete their styles.
For this example add-on, we will be storing our styles as a serialized array inside a wp_options table row with option_name my_em_styles. The array keys represent the style ID and the value is the name of that style. You could create your own table should you need to, in this case the wp_options table will do.
Step 3 – Add a meta box in the edit events page for users to select the event style
When managing events, we will need somewhere on the event registration form to choose from the list of styles. The event forms have various hooks for both the admin area and BuddyPress front end that allow us to insert extra event form elements. This provides a seamless integration with the rest of the plugin. We are going to make a new meta box for the event registration pages on the side of the admin area checklist.
Step 4 – Perform necessary actions when an event is added or updated
When events are saved, Events Manager will not automatically save the new form details we just added. Therefore we need to hook into the em_event_save filter and check if any styles were submitted along with the event information, and save it into our custom styles list. Learn how to save custom event information.
Step 5 – Attach style information to the event upon instantiation
When Events Manager retrieves event information from the database, it’s important for us to hook into this process and make the EM_Event object check if it has any styles assigned to it and load the relevant information. View how to add information to event objects on load
Step 6 – Make styles searchable via shortcode attributes
There are loads of attributes that you can use when searching for events via PHP, which enable you to quickly show events with powerful filtering options. Much like we could filter events by categories, locations, dates and more, it would be great if we could also filter the returned events by styles. So if we wanted, we could generate a list of events in London under categories “Dinners” with a “Formal” style by using something like:
[events_list category=2 town=”london” style=1]
After we add custom event search attributes, they can be used to filter events by style in any of the normal event/location/category search API methods, allowing for further features such as integrating with search forms.
Step 7 – Insert a style search drop-down menu into the events search form
Now that we can search events by style, why not take things a little further and add a drop down filter for styles in the search form on the events page? That way, users can quickly narrow down events of interest! Aside from you being able to directly modify the search form as a template by adding files to your theme folder, it’s possible to hook into another EM filter where you can just output the specific styles drop-down form.
Using filters has two advantages over templates:
- You, as a developer, could provide this as a plugin that doesn’t touch your client’s theme
- You don’t have to risk losing customizations if you update your theme (only worth it if you’re really making big changes)
- Template and php code for registering search variables remain in one place.
The disadvantage over templates is that you have limited flexibility. In this case, adding one form element is not worth adding a template file so let’s proceed to adding custom event search form fields with filters.
Step 8 – Add a custom placeholder for listing the event styles
Placeholders have been around since the early days of Events Manager. They are used for formatting your event output in the settings pages, and can also be supplied to shortcodes, template tags and objects to quickly and easily display specific information about an event. Therefore, given we’ll be using styles extensively on our imaginary website, we could really use a custom placeholder such as #_STYLES to show what kind of styles are.
For that we need to create a custom events placeholder.
Step 9 – Add a custom conditional placeholder for listing the event styles
Custom placeholders are new to Events Manager (introduced in 4.0) and allow us to hide specific content depending on a condition.
Wouldn’t it be nice if we could also format our events to show and hide certain information depending on what styles are associated with it? The new Events Manager API makes this pretty easy, and so we’ll add a dynamic custom placeholder that can show or hide information if the event in question has a certain style.
Step 10 – Create a new style pages that categorize events by style
Much like with categories and locations, it would be great to have a page that lists our styles and shows the upcoming events for each style. We’ll hook into the em_content_pre filter and check if the page requested is for our new styles pages. If so, we can override the event page content and prevent Events Manager from processing the output itself.
Step 11 – Create a new permalinks for styles
Whilst a new style page is nice, it would REALLY be nice if we could have a dedicated permalink that displays our styles and events. We can hook into WordPress in the same way Events Manager creates its permalinks and create custom wordpress permalink rules. Now we are able to view our styles from urls like mywebsite.com/events/styles/my-cool-style/
Wrapping Things Up
Wow, It’s getting hard to tell this plugin apart from the original now! This is really just a small example of what’s possible. In fact, many parts of Events Manager could actually be considered as add-ons and actually use filters much like we did just now to change the behaviour of Events Manager.
You can download a copy of the full source – Event Manager Styles Add-On (change this form txt to php extension and move this to your plugins or mu-plugins folder)
Interestingly, for many of these functions, you can simply search/replace event(s) with location(s) or category(ies) in this script using your text editor and the same functionality would apply to a location or category. Note that when replacing you should first replace plurals, then singulars, and make sure that you maintain capitalization.