The Events Manager plugin for WordPress can be used to build a fantastic event and calendaring system, with countless features and expandability, but there are times that the built in event attributes just aren’t enough. Thankfully the plugin is very developer friendly and allows users to create custom event attributes directly in the dashboard. However, what if you need to display a custom event attribute if it’s used, and not display it if it’s not used? That’s where event attribute conditional placeholders come in, however if you’re wanting to use a conditional placeholder with custom event attributes you’ll have to create it yourself. That’s what we’ll cover in this article.
Creating Custom Event Attributes
First in order to use a custom conditional placeholder you’ll need to have custom event attributes, so let’s create those first. To do this simply login to your WordPress dashboard and go to Events > Settings > General (tab) > General Options and scroll down until you find the radio input for “Enable event attributes?” and be sure that is set to “Yes”. Next you will need to scroll down to the “Event Attributes” text area and add your own custom event attributes. Note that in order for the custom conditional placeholder to function properly the custom event attribute should have no spaces, such as “#_ATT{this_is_my_custom_event_attribute}”. Also note that the custom event attribute is strictly case sensitive so be sure the exact same name is used throughout. For the sake of this article I will be creating a custom event attribute called test, so it will be added using the code below.
#_ATT{test}Once you’ve finished adding your custom event attributes be sure to save changes.
Creating Custom Conditional Placeholders
Next, we’ll add the necessary code to process our custom conditional placeholders. To do this we’ll implement the use of a filter hook that is called by the Events Manager plugin. Note that the code for the conditional placeholders will be added to your theme’s functions.php file. Thankfully the code for creating custom conditional placeholder is fairly simple, so I’ll show the code that I’ve used for the “test” custom event attribute and then explain how it works, and what you need to change.
function em_event_output_condition_filter($replacement, $condition, $match, $EM_Event){
// Checks for has_test conditional
if(is_object($EM_Event) && preg_match('/^has_(test)$/', $condition, $matches)){
if(array_key_exists($matches[1], $EM_Event->event_attributes) && !empty($EM_Event->event_attributes[$matches[1]]) ){
$replacement = preg_replace("/\{\/?$condition\}/", '', $match);
}else{
$replacement = '';
}
}
return $replacement;
}
add_filter('em_event_output_condition', 'em_event_output_condition_filter', 1, 4);It’s as simple as that! Once the above code has been added to the functions.php file the “#_ATT{test}” custom event attribute and “{has_test}” custom conditional placeholder are ready to be used.
Explaining the above code, we’re making use of the “em_event_output_condition” filter that is called by the Events Manager plugin each time it encounters a conditional placeholder that doesn’t match one of the built-in conditional placeholders.
Here is a description of the passed attributes:
- $replacement (string) will almost always be empty
- $condition (string) will be the custom conditional placeholder name (such as, “has_test”)
- $match (string) will contain the text from the beginning of the custom conditional placeholder to the end (such as, “{has_test} #_ATT{test} {/has_test}”)
- $EM_Event (event object) will be the event object of the current event being viewed
Essentially what the above code does is check for the existence of our custom conditional placeholder, then checks to see if the custom event attribute exists and if it has a non-empty value. If those conditions are met, then the content within the custom conditional placeholder, inside $match, is returned. If those conditions are not met then an empty string is returned.
Due to the simplicity of this filter, in order to modify the above code to work with your custom conditional placeholders simply change the word “test” on lines 2 and 3 to be the name of your custom event attribute, such as “my_custom_event_attribute”.
There you have it! You’ve now created a custom event attribute and a corresponding custom conditional placeholder. You may be wondering, “what if I need to create multiple custom conditional placeholders?”, or “where do I use the custom conditional placeholder?”, and I’ll cover both of those questions in the final section.
Wrapping Everything Up
In the case that you’re needing to create multiple custom conditional placeholders you simply duplicate a portion of the filter code above.
// Checks for has_test conditional
if(is_object($EM_Event) && preg_match('/^has_(test)$/', $condition, $matches)){
if(array_key_exists($matches[1], $EM_Event->event_attributes) && !empty($EM_Event->event_attributes[$matches[1]]) ){
$replacement = preg_replace("/\{\/?$condition\}/", '', $match);
}else{
$replacement = '';
}
}This is the code that actually does the processing, and duplicating it (and placing it above or below the existing code) and then replacing the custom event attribute with your additional custom event attribute is all you need to do. The reason that this works is because the Events Manager will call this filter *each* time it encounters a conditional placeholder that doesn’t match the built-in conditional placeholders. Note that your duplicated code MUST come before the line noted below.
return $replacement;
Lastly, in order for the custom event attribute and custom conditional placeholder to have any effect we need to add it to the front-end. The most common, and simple, way to do this is to login to your WordPress dashboard and then go to Events > Settings > Formatting (tab) > Events and scroll down to the “Default single event format” text area. This is where you can add your custom event attribute and custom conditional placeholder code where ever you’d like it to display on the single event page.
{has_test} This is an example of how to use the custom event attribute and display its value: #_ATT{test}, using a custom conditional placeholder.{/has_test}What About no_attribute Conditionals
Update – September 26, 2014: As a follow up to Koen’s question in the comments I’ve also added a snippet below that will allow you to use a conditional placeholder in the case that a custom attribute is not used.
// Checks for no_test conditional
if (is_object($EM_Event) && preg_match('/^no_(test)$/', $condition, $matches)) {
if ( !array_key_exists($matches[1], $EM_Event->event_attributes) || empty($EM_Event->event_attributes[$matches[1]]) ) {
$replacement = preg_replace("/\{\/?$condition\}/", '', $match);
} else {
$replacement = '';
}
}This can simply be used in addition to your other conditions (has_attribute or no_attribute) within the “em_event_output_condition_filter” filter function.
Nesting Conditionals
Update – October 23, 2014: If you plan to nest conditionals within other conditionals (whether they’re custom or built-in) you will first need to enable this functionality. By default the Events Manager plugin will only look for the first level of conditionals, and unfortunately there is no option for enabling conditional recurrence within the Events Manager Settings within the dashboard. Instead you will need to add some additional code to your functions.php theme file. Once the below code has been added you will need to go to the Events Manager Settings and click save (no changes necessary) to fire the “em_options_save” action. I used this action since this is technically updating an Events Manager option and it prevents the update_option method from being called each page load.
function lb_em_options_save() {
update_option('dbem_conditional_recursions', 2);
}
add_action('em_options_save', 'lb_em_options_save');
The Events Manager plugin checks for the dbem_conditional_recursions option upon instantiation. If this option is set it will use its value, and if not then it will use the default value of one. So, the above code sets the option value to two thus overriding the default. This will allow for one conditional to be nested within another, however you will need to adjust the above code if you plan nest conditionals at an even deeper level. Keep in mind high levels of recursion can negatively impact performance.
In Conclusion
Overall, the process of adding a custom event attribute and custom conditional placeholder is relatively simple and provides nearly infinite customizability to the Events Manager plugin. I hope this has been an easy to follow and informative guide on how to create custom event attributes. Be sure to post comments and let me know if you’ve ran into any problems or have any questions.
Leave a Reply