Skip to main content

Creating an Events Manager Add-On : A Complete Walkthrough

This series builds one small add-on, called Styles, from an empty file to a finished plugin. Each part adds one feature and uses one extension point of Events Manager, so you can also read a single part on its own when you need that technique.

The add-on lets you define a list of styles (Formal, Casual and so on), tick the styles that apply to each event, find events by style in shortcodes and the search form, and print an event's styles with a placeholder.

You may not need custom code for this

Styles behaves like a second set of categories. On a real site, registering a custom taxonomy for events gives you the same result with far less code, as shown in Extra taxonomies. The series stores its data by hand so that it can show how each hook works.

What you will build​

PartAddsExtension point
1. Admin pageA Styles page under the Events menu to add, rename and delete stylesadmin_menu and the events menu slug
2. Event meta boxStyle checkboxes in the event editor and the front-end event formadd_meta_boxes, em_front_event_form_footer
3. Save event dataStores the ticked styles, including for recurrencesem_event_save, em_recurrence_set_save_recurrences
4. Load event dataMakes $EM_Event->styles available everywhereem_event
5. Search attributesA style attribute for shortcodes and PHP queriesem_events_get_default_search, em_events_build_sql_conditions
6. Search form fieldsA style menu in the search formem_search_form_advanced_sections_footer
7. Custom placeholder#_STYLESem_event_output_placeholder
8. Conditional placeholders{has_style_1}, {has_styles}, {no_styles}em_event_output_show_condition
9. Multisite global tablesOne shared style list across a networkem_ms_globals
10. Custom event pagesA page per style under the events pageem_content_pre, em_content_page_title_pre
11. Custom permalinksReadable addresses for those pagesem_rewrite_rules_array_events
Before you start

You need Events Manager 7.5 or later, PHP 8.1 or later, a development site you can break, and working knowledge of PHP and WordPress hooks. Read Hooks and filters and PHP development first if the plugin's classes are new to you.

How the data is stored​

The add-on keeps two things:

  • The list of styles, as one WordPress option named my_em_styles holding an array of style ID to style name.
  • Which styles each event has, as rows in the Events Manager meta table. Each row has the event's event_id in object_id, the key event-style, and a style ID as its value. The table name comes from the EM_META_TABLE constant.

An option is a poor home for a list that could grow large, but it keeps the first part short and it lets part 9 show how network-wide options work.

Create the plugin file​

  1. Create the folder wp-content/plugins/my-em-styles/ and, inside it, the file my-em-styles.php. Where to add PHP explains why a plugin is a better home than a theme's functions.php.

  2. Paste in the starting code below. It has the plugin header and a function that will register every hook.

    wp-content/plugins/my-em-styles/my-em-styles.php
    <?php
    /**
    * Plugin Name: My EM Styles
    * Description: Example Events Manager add-on that lets you assign styles to events.
    * Version: 1.0.0
    * Requires PHP: 8.1
    */

    defined( 'ABSPATH' ) || exit;

    add_action( 'events_manager_loaded', 'my_em_styles_init' );
    function my_em_styles_init(): void {
    // Each part of the series adds its hooks here.
    }
  3. Under it, add the three helper functions shown below this list. The later parts use them to read and write the add-on's data.

  4. Activate My EM Styles in Plugins then Installed Plugins. Nothing visible changes yet.

Helper functions
/** All styles, as an array of style ID => name. */
function my_em_styles_get(): array {
$styles = get_option( 'my_em_styles' );
return is_array( $styles ) ? $styles : array();
}

/** The style IDs stored for one event. */
function my_em_styles_get_event_style_ids( int $event_id ): array {
global $wpdb;
if ( ! $event_id ) {
return array();
}
$ids = $wpdb->get_col( $wpdb->prepare( 'SELECT meta_value FROM ' . EM_META_TABLE . " WHERE object_id = %d AND meta_key = 'event-style'", $event_id ) );
return array_map( 'absint', $ids );
}

/** Replaces the styles stored for one event. */
function my_em_styles_set_event_style_ids( int $event_id, array $style_ids ): void {
global $wpdb;
if ( ! $event_id ) {
return;
}
$wpdb->delete( EM_META_TABLE, array( 'object_id' => $event_id, 'meta_key' => 'event-style' ), array( '%d', '%s' ) );
foreach ( array_unique( array_map( 'absint', $style_ids ) ) as $style_id ) {
$wpdb->insert( EM_META_TABLE, array( 'object_id' => $event_id, 'meta_key' => 'event-style', 'meta_value' => $style_id ), array( '%d', '%s', '%s' ) );
}
}

Registering the hooks inside a callback on events_manager_loaded means the add-on does nothing, and causes no errors, when Events Manager is not active. Two hooks in parts 9 and 11 are the exception and are added at file level, because Events Manager reads them earlier.

The helpers read and write through $wpdb->prepare(), $wpdb->insert() and $wpdb->delete(), so no value reaches SQL unescaped, and they cast IDs to integers on the way in and out.

The complete add-on​

This is the file as it stands at the end of part 11. Every part of the series shows the piece it adds.

wp-content/plugins/my-em-styles/my-em-styles.php
<?php
/**
* Plugin Name: My EM Styles
* Description: Example Events Manager add-on that lets you assign styles to events.
* Version: 1.0.0
* Requires PHP: 8.1
*/

defined( 'ABSPATH' ) || exit;

add_action( 'events_manager_loaded', 'my_em_styles_init' );
function my_em_styles_init(): void {
// 1. Admin page
add_action( 'admin_menu', 'my_em_styles_admin_menu', 20 );
// 2. Event meta box
add_action( 'add_meta_boxes', 'my_em_styles_meta_boxes' );
add_action( 'em_front_event_form_footer', 'my_em_styles_frontend_form_input' );
// 3. Save event data
add_filter( 'em_event_save', 'my_em_styles_event_save', 10, 2 );
add_filter( 'em_recurrence_set_save_recurrences', 'my_em_styles_save_recurrences', 10, 2 );
add_filter( 'em_event_delete', 'my_em_styles_event_delete', 10, 2 );
// 4. Load event data
add_action( 'em_event', 'my_em_styles_event_load' );
// 5. Search attributes
add_filter( 'em_events_get_default_search', 'my_em_styles_get_default_search', 10, 2 );
add_filter( 'em_calendar_get_default_search', 'my_em_styles_get_default_search', 10, 2 );
add_filter( 'em_events_build_sql_conditions', 'my_em_styles_build_sql_conditions', 10, 2 );
add_filter( 'em_locations_get_default_search', 'my_em_styles_get_default_search', 10, 2 );
add_filter( 'em_locations_build_sql_conditions', 'my_em_styles_build_sql_conditions', 10, 2 );
add_filter( 'em_locations_get_join_events_table', 'my_em_styles_locations_join_events_table', 10, 2 );
// 6. Search form field
add_action( 'em_search_form_advanced_sections_footer', 'my_em_styles_search_form_field' );
// 7. Placeholder
add_filter( 'em_event_output_placeholder', 'my_em_styles_placeholder', 10, 3 );
// 8. Conditional placeholder
add_filter( 'em_event_output_show_condition', 'my_em_styles_show_condition', 10, 4 );
// 10. Custom pages
add_filter( 'em_content_pre', 'my_em_styles_content' );
add_filter( 'em_content_page_title_pre', 'my_em_styles_page_title' );
}

// 9. Multisite global tables and 11. Permalinks hook in before events_manager_loaded fires.
add_filter( 'em_ms_globals', 'my_em_styles_ms_globals' );
add_filter( 'em_rewrite_rules_array_events', 'my_em_styles_rewrite_rules', 10, 2 );
add_filter( 'query_vars', 'my_em_styles_query_vars' );
register_activation_hook( __FILE__, 'my_em_styles_flush_rules' );
register_deactivation_hook( __FILE__, 'flush_rewrite_rules' );

/* ---------- Shared helpers ---------- */

/** All styles, as an array of style ID => name. */
function my_em_styles_get(): array {
$styles = get_option( 'my_em_styles' );
return is_array( $styles ) ? $styles : array();
}

/** The style IDs stored for one event. */
function my_em_styles_get_event_style_ids( int $event_id ): array {
global $wpdb;
if ( ! $event_id ) {
return array();
}
$ids = $wpdb->get_col( $wpdb->prepare( 'SELECT meta_value FROM ' . EM_META_TABLE . " WHERE object_id = %d AND meta_key = 'event-style'", $event_id ) );
return array_map( 'absint', $ids );
}

/** Replaces the styles stored for one event. */
function my_em_styles_set_event_style_ids( int $event_id, array $style_ids ): void {
global $wpdb;
if ( ! $event_id ) {
return;
}
$wpdb->delete( EM_META_TABLE, array( 'object_id' => $event_id, 'meta_key' => 'event-style' ), array( '%d', '%s' ) );
foreach ( array_unique( array_map( 'absint', $style_ids ) ) as $style_id ) {
$wpdb->insert( EM_META_TABLE, array( 'object_id' => $event_id, 'meta_key' => 'event-style', 'meta_value' => $style_id ), array( '%d', '%s', '%s' ) );
}
}

/* ---------- 1. Admin page ---------- */

function my_em_styles_admin_menu(): void {
if ( EM_MS_GLOBAL && ! is_main_site() ) {
return; // 9. In global tables mode, styles are managed on the main site only.
}
add_submenu_page( 'edit.php?post_type=' . EM_POST_TYPE_EVENT, 'Event Styles', 'Styles', 'edit_others_events', 'events-manager-styles', 'my_em_styles_admin_page' );
}

function my_em_styles_admin_url( array $args = array() ): string {
return add_query_arg( array_merge( array( 'post_type' => EM_POST_TYPE_EVENT, 'page' => 'events-manager-styles' ), $args ), admin_url( 'edit.php' ) );
}

function my_em_styles_admin_page(): void {
global $EM_Notices;
if ( ! current_user_can( 'edit_others_events' ) ) {
wp_die( esc_html__( 'You do not have permission to manage styles.', 'my-em-styles' ) );
}
$styles = my_em_styles_get();
$action = isset( $_POST['my_em_styles_action'] ) ? sanitize_key( $_POST['my_em_styles_action'] ) : '';
if ( $action === 'save' ) {
check_admin_referer( 'my_em_styles_save' );
$name = sanitize_text_field( wp_unslash( $_POST['style_name'] ?? '' ) );
$style_id = absint( $_POST['style_id'] ?? 0 );
if ( $name === '' ) {
$EM_Notices->add_error( esc_html__( 'Please enter a style name.', 'my-em-styles' ) );
} elseif ( $style_id && isset( $styles[ $style_id ] ) ) {
$styles[ $style_id ] = $name;
update_option( 'my_em_styles', $styles );
$EM_Notices->add_confirm( esc_html__( 'Style updated.', 'my-em-styles' ) );
} else {
$styles[ $styles ? max( array_keys( $styles ) ) + 1 : 1 ] = $name;
update_option( 'my_em_styles', $styles );
$EM_Notices->add_confirm( esc_html__( 'Style added.', 'my-em-styles' ) );
}
} elseif ( $action === 'delete' ) {
check_admin_referer( 'my_em_styles_delete' );
foreach ( array_map( 'absint', (array) ( $_POST['styles'] ?? array() ) ) as $style_id ) {
unset( $styles[ $style_id ] );
}
update_option( 'my_em_styles', $styles );
$EM_Notices->add_confirm( esc_html__( 'Styles deleted.', 'my-em-styles' ) );
}
$edit_id = absint( $_GET['style_id'] ?? 0 );
$editing = $edit_id && isset( $styles[ $edit_id ] );
?>
<div class="wrap">
<h1><?php esc_html_e( 'Event Styles', 'my-em-styles' ); ?></h1>
<?php echo $EM_Notices; ?>
<div id="col-container">
<div id="col-left"><div class="col-wrap"><div class="form-wrap">
<h2><?php echo $editing ? esc_html__( 'Edit style', 'my-em-styles' ) : esc_html__( 'Add style', 'my-em-styles' ); ?></h2>
<form method="post" action="<?php echo esc_url( my_em_styles_admin_url() ); ?>">
<input type="hidden" name="my_em_styles_action" value="save">
<?php wp_nonce_field( 'my_em_styles_save' ); ?>
<?php if ( $editing ) : ?>
<input type="hidden" name="style_id" value="<?php echo esc_attr( $edit_id ); ?>">
<?php endif; ?>
<div class="form-field form-required">
<label for="style-name"><?php esc_html_e( 'Style name', 'my-em-styles' ); ?></label>
<input id="style-name" name="style_name" type="text" value="<?php echo $editing ? esc_attr( $styles[ $edit_id ] ) : ''; ?>" required>
</div>
<?php submit_button( $editing ? __( 'Update style', 'my-em-styles' ) : __( 'Add style', 'my-em-styles' ) ); ?>
</form>
</div></div></div>
<div id="col-right"><div class="col-wrap">
<?php if ( $styles ) : ?>
<form method="post" action="<?php echo esc_url( my_em_styles_admin_url() ); ?>">
<input type="hidden" name="my_em_styles_action" value="delete">
<?php wp_nonce_field( 'my_em_styles_delete' ); ?>
<table class="wp-list-table widefat striped">
<thead><tr>
<td class="check-column"></td>
<th><?php esc_html_e( 'ID', 'my-em-styles' ); ?></th>
<th><?php esc_html_e( 'Name', 'my-em-styles' ); ?></th>
</tr></thead>
<tbody>
<?php foreach ( $styles as $style_id => $style_name ) : ?>
<tr>
<th class="check-column"><input type="checkbox" name="styles[]" value="<?php echo esc_attr( $style_id ); ?>"></th>
<td><?php echo esc_html( $style_id ); ?></td>
<td><a href="<?php echo esc_url( my_em_styles_admin_url( array( 'style_id' => $style_id ) ) ); ?>"><?php echo esc_html( $style_name ); ?></a></td>
</tr>
<?php endforeach; ?>
</tbody>
</table>
<?php submit_button( __( 'Delete selected', 'my-em-styles' ), 'delete' ); ?>
</form>
<?php else : ?>
<p><?php esc_html_e( 'No styles yet. Add your first one with the form on the left.', 'my-em-styles' ); ?></p>
<?php endif; ?>
</div></div>
</div>
</div>
<?php
}

/* ---------- 2. Event meta box ---------- */

function my_em_styles_meta_boxes(): void {
add_meta_box( 'em-event-styles', __( 'Styles', 'my-em-styles' ), 'my_em_styles_fields', array( EM_POST_TYPE_EVENT, 'event-recurring' ), 'side', 'low' );
}

function my_em_styles_fields(): void {
global $EM_Event;
$selected = $EM_Event instanceof EM_Event && is_array( $EM_Event->styles ) ? $EM_Event->styles : array();
wp_nonce_field( 'my_em_styles_event', 'my_em_styles_nonce' );
foreach ( my_em_styles_get() as $style_id => $style_name ) {
printf(
'<label><input type="checkbox" name="event_styles[]" value="%d" %s> %s</label><br>',
absint( $style_id ),
checked( in_array( (int) $style_id, $selected, true ), true, false ),
esc_html( $style_name )
);
}
}

function my_em_styles_frontend_form_input(): void {
if ( ! my_em_styles_get() ) {
return;
}
?>
<section class="event-form-styles">
<h3><?php esc_html_e( 'Styles', 'my-em-styles' ); ?></h3>
<div class="input"><?php my_em_styles_fields(); ?></div>
</section>
<?php
}

/* ---------- 3. Save event data ---------- */

/** The style IDs submitted with the event form, or null if our fields were not part of this request. */
function my_em_styles_posted_ids(): ?array {
if ( empty( $_POST['my_em_styles_nonce'] ) || ! wp_verify_nonce( sanitize_key( $_POST['my_em_styles_nonce'] ), 'my_em_styles_event' ) ) {
return null;
}
$posted = array_map( 'absint', (array) ( $_POST['event_styles'] ?? array() ) );
return array_values( array_intersect( $posted, array_keys( my_em_styles_get() ) ) );
}

function my_em_styles_event_save( $result, $EM_Event ) {
$style_ids = my_em_styles_posted_ids();
if ( $style_ids === null || ! $EM_Event->event_id ) {
return $result;
}
my_em_styles_set_event_style_ids( (int) $EM_Event->event_id, $style_ids );
$EM_Event->styles = $style_ids;
return $result;
}

function my_em_styles_save_recurrences( $result, $Recurrence_Set ) {
if ( ! $result ) {
return $result;
}
$style_ids = my_em_styles_posted_ids() ?? my_em_styles_get_event_style_ids( (int) $Recurrence_Set->get_event()->event_id );
foreach ( $Recurrence_Set->get_recurrences() as $recurrence ) {
if ( ! empty( $recurrence['event_id'] ) ) {
my_em_styles_set_event_style_ids( (int) $recurrence['event_id'], $style_ids );
}
}
return $result;
}

function my_em_styles_event_delete( $result, $EM_Event ) {
if ( $result && $EM_Event->event_id ) {
my_em_styles_set_event_style_ids( (int) $EM_Event->event_id, array() );
}
return $result;
}

/* ---------- 4. Load event data ---------- */

function my_em_styles_event_load( $EM_Event ): void {
$EM_Event->styles = my_em_styles_get_event_style_ids( (int) $EM_Event->event_id );
}

/* ---------- 5. Search attributes ---------- */

function my_em_styles_get_default_search( $args, $array ) {
$args['style'] = false;
if ( ! empty( $array['style'] ) && is_numeric( $array['style'] ) ) {
$args['style'] = absint( $array['style'] );
}
return $args;
}

function my_em_styles_build_sql_conditions( $conditions, $args ) {
global $wpdb;
if ( ! empty( $args['style'] ) && is_numeric( $args['style'] ) ) {
$subquery = $wpdb->prepare( 'SELECT object_id FROM ' . EM_META_TABLE . " WHERE meta_key = 'event-style' AND meta_value = %s", absint( $args['style'] ) );
$conditions['style'] = EM_EVENTS_TABLE . ".event_id IN ( $subquery )";
}
return $conditions;
}

function my_em_styles_locations_join_events_table( $join, $args ) {
return ! empty( $args['style'] ) ? true : $join;
}

/* ---------- 6. Search form field ---------- */

function my_em_styles_search_form_field( $args ): void {
$styles = my_em_styles_get();
if ( ! $styles ) {
return;
}
$selected = absint( $args['style'] ?? ( $_REQUEST['style'] ?? 0 ) );
$field_id = 'em-search-style-' . absint( $args['id'] ?? 0 );
?>
<section class="em-search-section-styles em-search-advanced-section">
<header><?php esc_html_e( 'Style', 'my-em-styles' ); ?></header>
<div class="em-search-section-content">
<div class="em-search-style em-search-field">
<label for="<?php echo esc_attr( $field_id ); ?>" class="screen-reader-text"><?php esc_html_e( 'Style', 'my-em-styles' ); ?></label>
<select name="style" id="<?php echo esc_attr( $field_id ); ?>">
<option value=""><?php esc_html_e( 'All styles', 'my-em-styles' ); ?></option>
<?php foreach ( $styles as $style_id => $style_name ) : ?>
<option value="<?php echo esc_attr( $style_id ); ?>" <?php selected( $selected, (int) $style_id ); ?>><?php echo esc_html( $style_name ); ?></option>
<?php endforeach; ?>
</select>
</div>
</div>
</section>
<?php
}

/* ---------- 7. Placeholder ---------- */

function my_em_styles_placeholder( $replace, $EM_Event, $full_result ) {
if ( $full_result !== '#_STYLES' ) {
return $replace;
}
$names = array_intersect_key( my_em_styles_get(), array_flip( (array) $EM_Event->styles ) );
return $names ? esc_html( implode( ', ', $names ) ) : esc_html__( 'none', 'my-em-styles' );
}

/* ---------- 8. Conditional placeholder ---------- */

function my_em_styles_show_condition( $show, $condition, $full_match, $EM_Event ) {
$event_styles = (array) $EM_Event->styles;
if ( $condition === 'has_styles' ) {
return ! empty( $event_styles );
}
if ( $condition === 'no_styles' ) {
return empty( $event_styles );
}
if ( preg_match( '/^has_style_(\d+)$/', $condition, $matches ) ) {
return in_array( (int) $matches[1], $event_styles, true );
}
return $show;
}

/* ---------- 9. Multisite global tables ---------- */

function my_em_styles_ms_globals( $globals ) {
if ( EM_MS_GLOBAL ) {
$globals[] = 'my_em_styles';
}
return $globals;
}

/* ---------- 10. Custom pages ---------- */

function my_em_styles_content( $content ) {
$styles = my_em_styles_get();
$style_id = absint( get_query_var( 'style_id' ) );
if ( $style_id && isset( $styles[ $style_id ] ) ) {
$content = '<p>' . sprintf( esc_html__( 'Upcoming events with the %s style', 'my-em-styles' ), '<strong>' . esc_html( $styles[ $style_id ] ) . '</strong>' ) . '</p>';
$content .= EM_Events::output( array( 'style' => $style_id, 'scope' => 'future' ) );
} elseif ( get_query_var( 'styles_page' ) ) {
foreach ( $styles as $id => $name ) {
$content .= '<h3>' . esc_html( $name ) . '</h3>';
$content .= EM_Events::output( array( 'style' => $id, 'scope' => 'future', 'limit' => 5, 'pagination' => 0 ) );
}
}
return $content;
}

function my_em_styles_page_title( $title ) {
$styles = my_em_styles_get();
$style_id = absint( get_query_var( 'style_id' ) );
if ( $style_id && isset( $styles[ $style_id ] ) ) {
return esc_html( $styles[ $style_id ] );
}
if ( get_query_var( 'styles_page' ) ) {
return esc_html__( 'Styles', 'my-em-styles' );
}
return $title;
}

/* ---------- 11. Permalinks ---------- */

function my_em_styles_rewrite_rules( $rules, $events_slug ) {
$page = trim( $events_slug, '/' );
if ( $page !== '' ) {
$rules[ $page . '/styles/?$' ] = 'index.php?pagename=' . $page . '&styles_page=1';
$rules[ $page . '/style/(\d+)/?$' ] = 'index.php?pagename=' . $page . '&style_id=$matches[1]';
}
return $rules;
}

function my_em_styles_query_vars( $vars ) {
$vars[] = 'style_id';
$vars[] = 'styles_page';
return $vars;
}

function my_em_styles_flush_rules(): void {
flush_rewrite_rules();
}
The older Styles plugin

An earlier version of this add-on was published as "Events Manager Styles" for Events Manager 5. It uses the same function names, so deactivate it before you activate the file above.

Start the series​

Part 1: Admin page