Skip to main content

Create a Custom Placeholder for Event Formatting

This tutorial forms part of our series of tutorials for creating an custom add-on for Events Manager called “Styles”, where we will be able to select from a list of styles during event registration. In our previous tutorial, we added a custom field to the events search form.

Events Manager uses placeholders like #_EVENTNAME so that you can easily insert snippets of html via the events settings page and change the way events, locations, categories and contact information are displayed. Moreover, you can use these in shortcodes, template tags, or when directly working with objects.

Advantages and uses for custom placeholders​

The great thing about placeholders is you can easily insert chunks of information with one word. Events Manager 3 onwards also has the ability for you to use your own custom placeholders or modify the way the default placeholders work. This could have many uses:

  • Create a shortcut placeholder you can use across many formats.
  • Adding a new placeholder for extra event information you have added to Events Manager
  • Use placeholders to do execute custom PHP code whilst displaying event information.
  • Change the formatting or behaviour of current placeholders

Adding your own placeholder​

In this tutorial, we're going to extend our custom Events Manager addon "Styles" plugin by adding a #_STYLES placeholder, which prints a comma separated list of the styles our event has.

So, here's the code needed to do this:

add_filter('em_event_output_placeholder','my_em_styles_placeholders',1,3);
function my_em_styles_placeholders($replace, $EM_Event, $result){
    if( $result == '#_STYLES' ){
        $replace = 'none';
        if( count($EM_Event->styles) > 0 ){
            $my_em_styles = (is_array(get_option('my_em_styles'))) ? get_option('my_em_styles'):array();
            $styles = array();
            foreach( $EM_Event->styles as $id ){
                if( !empty($my_em_styles[$id]) ){
                    $styles[] = $my_em_styles[$id];
                }
            }
            $replace = implode(', ', $styles);
        }
    }
    return $replace;
}

We start off by adding a filter for the em_event_output_placeholder filter. This function will get called every time a placeholder is found in the current format being output, and therefore can be used to create a custom placeholder, or modify an existing one.

This filter returns four variables:

  • $replace is the value of what this placeholder would be replaced with (and since this is not an EM placeholder, this would always be an empty string).
  • $EM_Event is the EM_Event object currently being output.
  • $result is the placeholder currently being parsed.
  • $target (not used in this case) contains the intended target for this content we're outputting, which could be html (default), rss, ical, map (for google map ballons), and email.

We use $result to check that we are dealing with a #_STYLES placeholder. If we find a match, we will firstly set the default $replace to 'none' so that if nothing is found a blank value isn't used (although leaving a blank value is perfectly fine if that's what you want).

Lets focus on this bit:

if( count($EM_Event->styles) > 0 ){
    $my_em_styles = (is_array(get_option('my_em_styles'))) ? get_option('my_em_styles'):array();
    $styles = array();
    foreach( $EM_Event->styles as $id ){

Here we check the object is EM_Event and has more than one style, which we loaded on event instantiation.

If the event has one or more styles associated with it, we load the full list of styles for reference from the wp_options database into $my_em_styles. We then loop through the event style IDs to obtain the names of each style from $my_em_styles. As we find the relevant styles, we add them to a $styles array and finally save that a comma separated list to $replace.

In the end, once we've done our processing, we return $replace to the filter, whether we ended up modifying it or not, so other placeholders being processed remain untouched.

As you can see, there's no limit to what you can do and choose to output once you've hooked into the right placeholder name. We'll leave that bit up to you....

Further consideration - placeholder arguments​

Whilst we don't make use of it here, some implementations may find the ability to pass arguments along with placeholders useful. For example, #_EVENTEXCERPT accepts brackets at the end containing the desired word length of the except, and an optional second argument which would be the ending cut-off text such as #_EVENTEXCERPT{10,more...}.

In the event you'll accept extra arguments in your placeholder, $result will contain the full placeholder with the brackets, therefore you would need to alter your code accordingly to check you still have a #_STYLES placeholder, and then parse the bracket arguments. Like so for example:

if( preg_match('/^#_STYLES\{?/', $result) ){
    $args = explode(',', preg_replace('/#_STYLES\{(.+)\}/', '$1', $result));
}

Next Steps...​

In the following tutorial, we're going to learn how to create a custom conditional placeholder for your events.