Support

December 12, 2014 at 2:28 am

Hey guys,

I’ve been pulling my hair out trying to figure out how to manipulate and override the way Event Espresso works and displays information. The documentation pages might help people already knowing what to do, but I don’t, so they haven’t been much help.

I finally think I’ve managed to understand a couple of things, so to help other newbies like myself to override default Event Espresso functionality, I figured I’d try to write this post explaining how.

I’ve probably misunderstood at least a couple of things, so if anyone have corrections or pointers, please feel free to add your comments in the replies.

I also have some questions and suggestions for improvements to the Event Espresso core (unless they also are misunderstandings, of course), so perhaps someone with more insight than me can provide some further help with these questions.

This walk-through is based on overriding the «Thank you»-page you land on after registering for an event.

==== PART 1: By filters and actions ====
The documentation page gives some hints as to how to override the things happening on this page:
https://eventespresso.com/wiki/ee4-thank-page-actions-filters-hooks/

Under «Existing», you see two filters. You might not know what a filter is, I sure didn’t. But reading this helped alot:
http://wordpress.stackexchange.com/questions/16573/explanation-for-apply-filters-function-and-its-variables

So, we’ll start out by taking a look at the file we want to alter, located in [event espresso plugin folder]/shortcodes/espresso_thank_you/templates/thank-you-page-overview.template.php. This is the file outputting the thank you-page.

As you’ll se, the file contains several actions and one filter. To change the Congratulations text, we need to hook into the filter. The filter is named FHEE__thank_you_page_overview_template__order_conf_desc, and as you can see in the file, what it does is simply output the congratulations text.

To hook into the filter, open your theme’s functions.php file (or better, make a site specific plugin, as explained here: https://eventespresso.com/wiki/create-site-specific-plugin-wordpress-site/ . That way you won’t risk loosing your changes if your theme gets updated.)

In the functions.php in your theme or in the main site specific plugin file, add the following code:


add_filter( 'FHEE__thank_you_page_overview_template__order_conf_desc', 'custom_congratulations_message' );

function custom_congratulations_message() {
// Add your code here, for example:
echo "<h2>Hurray!</h2><p>You’re registered for our event. See ya!";
}


What this little piece of code does is hook into the filter named FHEE__thank_you_page_overview_template__order_conf_desc, and replace it with the function named custom_congratulations_message. Then, in the function named custom_congratulations_message, the desired output is generated. To display your own text, change the text in the custom_congratulations_message function. You can also add other functionality here if you want to.

Some filters have variables passed to them, for example to loop through arrays or format content. If that’s the case, you’ll need to process the array and return the content in the same format the original filter does.

A similar way of controlling the content is also available for content presented from do_action (instead of apply_filter). That’ll have to wait until another time, I’m not sure how to do it myself yet. (But this seems like an okay place to start: http://frumph.net/2010/06/14/understanding-do_action-and-add_action/ )

So, to alter content in the various parts of Event Espresso, here’s a shorthand list of what you need to do:
1. Identify which php file in Event Espresso that outputs the content you want to alter
2. Hope that the content is outputted by (or after) apply_filter or do_action, so you can manipulate it
3. Create an add_filter or add_action block in your functions.php/site specific plugin file and generate your output
4. Enjoy!

==== PART 2: Direct template replacement ====
Personally, I find that method unnecessary complicated. After all, both the main framework of the page and its different sections are produced by simple php files that are supposed to work like templates. Wouldn’t it be easier to duplicate them into a folder that won’t be altered in future Event Espresso updates, and edit them there? Other parts of the Event Espresso system work this way.

If so, the easiest way would be to create my own thank-you-page-registration-details.template.php, and put it in a place Event Espresso could find it. However, I can’t seem to get it loaded by Event Espresso, no matter where the template file is placed.

I’ve tried these locations:

wp-content/themes/themefolder/thank-you-page-registration-details.template.php
wp-content/themes/themefolder/shortcodes/espresso_thank_you/templates/thank-you-page-registration-details.template.php
wp-content/uploads/espresso/templates/thank-you-page-registration-details.template.php
wp-content/uploads/espresso/templates/shortcodes/espresso_thank_you/templates/thank-you-page-registration-details.template.php


I have, however, also made an attempt at finding out why it doesn’t work, and I think I’ve found a possible solution.

But first, the problem:

The template file is loaded like this in shortcodes/espresso_thank_you/EES_Espresso_Thank_You.shortcode.php:

echo EEH_Template::locate_template( THANK_YOU_TEMPLATES_PATH . 'thank-you-page-registration-details.template.php', $template_args, TRUE, TRUE );

The locate_template function is then loaded. This is located in core/helpers/EEH_Template.helper.php.

The locate_template function basically loops through a bunch of template folders looking for our file – or at least it’s supposed to.

When echoing the contents of the arrays it’s working with, it seems as most of the custom locations are lost somewhere in the process.

At one point in locate_template it loops through the array of possible template locations, creating the final array that will eventually be checked (around line 215 in EEH_Template.helper.php).

The template path to be checked is constructed like this:
$full_template_paths[] = rtrim( $template_folder_path, DS ) . DS . $template;

This causes problems. Because the locate_template is loaded with the THANK_YOU_TEMPLATES_PATH appended, the $full_template_paths array gets several entries with double absolute paths, e.g. in my case like this:
/www/html/vhost/sitename.com/wp-content/uploads/espresso/templates//www/html/vhost/sitename.com/wp-content/plugins/event-espresso/shortcodes/espresso_thank_you/templates/thank-you-page-registration-details.template.php

So, it’s understandable that it can’t find my custom template file, seeing as the path and file doesn’t exist on my system.

I figure there are two ways of fixing this.
1. Alter the way the template is called from EES_Espresso_Thank_You.shortcode.php – By making THANK_YOU_TEMPLATES_PATH only contain the «local» path (starting with shortcodes/etc), not the full server path
2. Alter the way the templates are searched for in EEH_Template.helper.php

I have only tried and tested method 2, and as far as I can see, it works.

Here is what I did:

Open EEH_Template.helper.php.

Find the locate_template function (around line 156).

Around line 209, there is a foreach that starts like this:

// loop through $templates
foreach ( (array)$templates as $template ) {
// while looping through all template folder paths
foreach ( (array)$template_folder_paths as $template_folder_path ) {


After that last quoted line of code, add this:

$templatefile = basename($template);


The next line of code in the file should be something like this:

$full_template_paths[] = rtrim( $template_folder_path, DS ) . DS . $template;


Add this right after it:

$full_template_paths[] = $template_folder_path . $templatefile;


Then, a little further on in the function, you’ll see a foreach that starts like this:

// now loop through our final array of template location paths and check each location
foreach ( (array)$full_template_paths as $full_template_path ) {


BEFORE that foreach, add the following:

rsort($full_template_paths);


Then you should be good to go! Now, all template files added in uploads/espresso/templates/ with the same file name as the original template file, will get loaded in stead of the original template file. If you remove (or rename) your override template file, the original file is loaded again. All the default checks are still being run, so other parts of the system using locate_template still works as normal.

So, if you want to alter the Thank you page, you’ll have to copy the /shortcodes/espresso_thank_you/templates/thank-you-page-overview.template.php file to uploads/espresso/templates/, and edit it there. Parts of the page is made with other php files in the same folder, so feel free to copy them over as well as needed.

Here’s what the code added to EEH_Template.helper.php above does:
– Put the file name in a variable by itself
– Add the (short and correct) path and the file name to the array of files being checked for existence
– Sort the array reversed alphabetically. That way, wp-content/uploads will be checked before wp-content/plugins, and thus any custom template files placed in the uploads directory will be used in stead of the original ones. (There’s probably a more elegant way of accomplishing this.)

A big warning and heads up, though: The downside to this, of course, is that it requires altering a core file. So, that’s why I’m guessing I might be off – perhaps there’s an even easier way to do this? Perhaps adding your own custom php files in the template directory should work already? (Even though it won’t work on my setup, at least. Any help on figuring out why is much appriciated.)

If there is no way around altering the core to achieve this, I hope the Event Espresso staff will consider altering EEH_Template.helper.php as described (or similar) so this way of customizing Event Espresso can be possible in the future. It would make a great system even better and more flexible. Also, adding a more understandable and easy documentation would also be nice.

Anyway, thank you for your attention, and as stated at the beginning, I’m expecting to be wrong about all or parts of this, so please feel free to both correct and enlighten me.

All the best,
Eivind