Custom Templates Add-on – Create a Template

Basics

First off I want to briefly explain how the plugin works. It is a simple one file plugin that looks for template folders/files in the plugin directory or the theme that match the template_name parameter in the shortcode (e.g. [EVENT_CUSTOM_VIEW template_name=”category-filter”]) will look for the category-filter folder/file. This core file will do some some of the heavy lifting for you already, it grabs the event list details for you, and works out all the parameters such as limit, or show_recurrence. This means that your custom template for the most part should only require a structure. Sometimes though, you may need to re-query the database for additional data. Take the category-filter template I worked on, it queried the database in the template file in order to get the category details in order to output them into a “select” drop down box.

Custom Parameters

It is possible to use custom parameters in the shortcodes as well, for example [EVENT_CUSTOM_VIEW template_name=”grid” my_custom_parameter=”something”] The template will need the array $ee_attributes adding to the global list. Some of the default arrays use this and some don’t, but it can be added to any of them. Then simply get the parameter value into a variable to use, e.g.: $myvariable = $ee_attributes[‘mycustom_parameter’]; If you echo $myvariable the result will be  something.

Example Template

I am going to go through a process of creating a grid like structure for the events.  This isn’t a follow and copy exercise, more like a broad generalisation of what I did. I began by grabbing one of the existing templates that matches my idea broadly and copy the folder and rename it. In this case I am just using the calendar table template as it has CSS already loaded that I can hijack. I delete any files that aren’t necessary usually leaving me with just the index.php file. Opening up the index.php there are some things that need to be changed straight away. First off are the comments at the top. This isn’t vital, but useful to keep track of what the file is about. I ended up with these comments:

//Template: Grid
//Description: This template creates a grid style view of events.
//Shortcode Example: [EVENT_CUSTOM_VIEW template_name="grid-view" max_days="30" category_identifier="concerts"]. 
//Requirements: CSS skills to customize styles, HTML/PHP to restructure.
//The end of the action name (example: "action_hook_espresso_custom_template_") should match the name of the template. In this example, the last part the action name is "grid-view",
	

Now if you have read those comments, the last one, mentioning the action hook is our next step. You will see code like this:

add_action('action_hook_espresso_custom_template_default','espresso_custom_template_default');
function espresso_custom_template_default(){
	

It needs to be changed to have the correct name for your file/folder. As the template is called Grid, mine will look like this:

add_action('action_hook_espresso_custom_template_grid','espresso_custom_template_grid');
function espresso_custom_template_grid(){
	

If you have done that correctly, you should be able to load up the template in a page or post. Obviously it will look like the basic template you have copied from, but if it hasn’t been set up correctly you will know as you will get an empty page.  Important: If you are using two words in the template name, such as grid view, the first part of the add_action needs to use a dash ( – ) instead of the space. The second part of it and the function name should use an underscore ( _ ). The folder/file name should use a dash as a replacement for the space. For example:

add_action('action_hook_espresso_custom_template_grid-view','espresso_custom_template_grid_view');
function espresso_custom_template_grid_view(){
	

Now it is about getting down and modifying the template itself. One thing to note is that all the data is held in an array called $events, and the template will use a foreach loop to go through each one. There is little point changing this as it is needed. As such in the template sections you will be called data like so $event->event_name ($event is a an array for one event, $events is the array of ALL the events, which is why you use the singular version here). To begin with I am going to keep it simple and create a grid structure that has the featured image and event title, both linking to the event registration page. Once that is done, its fairly simple to start adding extra details such as prices, and extra styles such as hover effects etc. I tend to get the structure thought out in another file before adding it into the template, it helps me to get the basics right before implementing it.

<div><!-- the overall surrounding div -->
<div><!-- an individual grid box -->
<a href=""><img id="" class="" src=""  /></a>
<a href=""><h2 id="" class=""></h2></a>
</div>
</div>
	

That’s it for now. I then replace the table that’s there with this code, being mindful that the surrounding div needs to be outside the loop, just like the

<table>
	

tags and the rest inside the foreach loop. Mainly I’ll be focusing where the

<tr>
	

tag starts and ends. To get the featured image I needed to do some magic with the PHP code. In the foreach each loop, I added

$image_url = unserialize($event->event_meta);
	

What this does is give me an array of that events event_meta. Meaning in the image HTML I can use that array to get the featured image. Here is my foreach loop

		<div class="">

		<?php 
		foreach ($events as $event){
			//Debug
			$this_event_id		= $event->id;
			$member_only		= !empty($event->member_only) ? $event->member_only : '';
			$externalURL 		= $event->externalURL;
			$registration_url 	= !empty($externalURL) ? $externalURL : espresso_reg_url($event->id);
			$live_button 		= '<a id="a_register_link-'.$event->id.'" href="'.$registration_url.'"><img class="buytix_button" src="'.ESPRESSO_CUSTOM_DISPLAY_PLUGINPATH.'/templates/default/register-now.png" alt="Buy Tickets"></a>';
			$open_spots 		= apply_filters('filter_hook_espresso_get_num_available_spaces', $event->id);
			
			//This line changes the button text to display "Closed" if the attendee limit is reached.
			
			$image_url = unserialize($event->event_meta);
			if ( $open_spots < 1 ) { $live_button = 'Closed';  }
			
			
		
			//Gets the member options, if the Members add-on is installed.
			$member_options = get_option('events_member_settings');
	
			//If enough spaces exist then show the form
			//Check to see if the Members plugin is installed.
			if ( function_exists('espresso_members_installed') && espresso_members_installed() == true && !is_user_logged_in() && ($member_only == 'Y' || $member_options['member_only_all'] == 'Y') ) {
				event_espresso_user_login();
			}else{
				?>
            <div>
                <a href="<?php echo $registration_url; ?>"><img id="" class="" src="<?php echo $image_url['event_thumbnail_url']; ?>"  /></a>
                <a href="<?php echo $registration_url; ?>"><h2 id="" class=""><?php echo $event->event_name; ?></h2></a>
            </div>
		<?php
			}// close is_user_logged_in	
		 } //close foreach ?>
	</div>
	

As you can see I have left some of the original code in there, but that can be removed later. This doesn’t much look like a grid, but if we change the code so that the file sees the CSS file, then add a CSS class to the inner div tag and some CSS, that will quickly change. This is the entire index.php in its rough format (honestly, it is very rough!)

<?php 
//Template: Grid View
//Description: This template creates a grid style view of events.
//Shortcode Example: [EVENT_CUSTOM_VIEW template_name="grid-view" max_days="30" category_identifier="concerts"]. 
//Requirements: CSS skills to customize styles, HTML/PHP to restructure.
//The end of the action name (example: "action_hook_espresso_custom_template_") should match the name of the template. In this example, the last part the action name is "grid-view",
 
add_action('action_hook_espresso_custom_template_grid','espresso_custom_template_grid');

function espresso_custom_template_grid(){
	//Load the css file
	wp_register_style( 'espresso_cal_table_css', ESPRESSO_CUSTOM_DISPLAY_PLUGINPATH."/templates/grid/style.css" );
	wp_enqueue_style( 'espresso_cal_table_css');
	
	//Defaults
	global $org_options, $this_event_id, $events;
	$featured_image = FALSE; //Show the featured image for each event, instead of the date, to the left of the event title.
	$temp_month = ''; //Clears the month name
	
	//Uncomment to view the data being passed to this file
	//echo '<h4>$events : ' . print_r($events,true) . ' <span style="font-size:10px;font-weight:normal;">' . __FILE__ . '<br />line no: ' . __LINE__ . '</span></h4>';
	
	?>
	<div class="">

		<?php 
		foreach ($events as $event){
			//Debug
			$this_event_id		= $event->id;
			$member_only		= !empty($event->member_only) ? $event->member_only : '';
			$externalURL 		= $event->externalURL;
			$registration_url 	= !empty($externalURL) ? $externalURL : espresso_reg_url($event->id);
			$live_button 		= '<a id="a_register_link-'.$event->id.'" href="'.$registration_url.'"><img class="buytix_button" src="'.ESPRESSO_CUSTOM_DISPLAY_PLUGINPATH.'/templates/grid/register-now.png" alt="Buy Tickets"></a>';
			$open_spots 		= apply_filters('filter_hook_espresso_get_num_available_spaces', $event->id);
			
			//This line changes the button text to display "Closed" if the attendee limit is reached.
			
			$image_url = unserialize($event->event_meta);
			if ( $open_spots < 1 ) { $live_button = 'Closed';  }
			
			
		
			//Gets the member options, if the Members add-on is installed.
			$member_options = get_option('events_member_settings');
	
			//If enough spaces exist then show the form
			//Check to see if the Members plugin is installed.
			if ( function_exists('espresso_members_installed') && espresso_members_installed() == true && !is_user_logged_in() && ($member_only == 'Y' || $member_options['member_only_all'] == 'Y') ) {
				event_espresso_user_login();
			}else{
				?>
            <div class="ee_grid">
                <a href="<?php echo $registration_url; ?>"><img id="" class="" src="<?php echo $image_url['event_thumbnail_url']; ?>"  /></a>
                <a href="<?php echo $registration_url; ?>"><h2 id="" class=""><?php echo $event->event_name; ?></h2></a>
            </div>
		<?php
			}// close is_user_logged_in	
		 } //close foreach ?>
	</div>
	
<?php } ?>
	

And the CSS

.ee_grid {
	width:188px;
	margin:10px;
	float:left;
}
.ee_grid img {
	width:188px;
	height:188px;
}