Add a Custom Page Template to WordPress Thesis Theme

Thesis is a popular premium WordPress theme. Unlike many themes that are implemented to plug directly into the WordPress-defined template structure, Thesis is a force unto itself. It’s a framework that completely redefines the approach to WordPress customization. It achieves this by supplying a rich set of hooks into the various stages of the page generation process and then creates one location where all customization code goes. One file – custom_functions.php – holds all the custom code and is safe from overwriting during theme upgrades.

The Thesis framework is sufficient for a wide range of customization needs. However, as with all popular software, users’ needs eventually go beyond the default capabilities of the software. Thesis has in-built support for creating 2-column and 3-column sites. The layouts are configured via the Design Options menu and apply site-wide. You can override the layout of particular pages (eg home page) by intercepting the page generation process in custom_functions.php. The problem with this approach is that you have to know the designation (home), name or id of the page before-hand as you customize the site. If these details change after the site has been launched, then the customization code is going to break.

Page Template List

What if you want to alter the layout of an arbitrary number of pages that are going to be created in the future? All you know at customization time is what the layout shall be, but not which particular pages shall use it. This obviously calls for a solution that does not involve updating the customization code every time a page requires the custom layout. Even better, it calls for a facility that can be triggered while the page is being created by the user. A facility such as the WordPress  page Template selection drop-down. If you could create a custom template and have it selectable on the Template drop-down, then the user would simply pick it during page creation (or editing) and have it used for page rendering.

Thesis (version 1.6) does not support plugging in of custom template files, but it is flexible enough to pick them up if you know where to tweak. Here’s how you go about doing exactly that:

1)       Problem description

The hypothetical site we shall be working with is a travel blog. The site has various sections, but the one that is of interest here is one called Places. It has pages describing various travel destinations. These pages have advertising that shows in the left column. Every other type of page on the site does not have this left column and therefore no ads showing. How do we get the ads to show on the Places pages, but not on any other page?

2)       Create the page template file

The Thesis theme has a convention, where customization code is stored in the /wp-content/themes/thesis/custom/ folder. The standard customization files in this folder are custom_functions.php and custom.css for code and styling respectively. This is the folder where you shall put the new custom template file places_template_functions.php. The code for the template file is:

<?php
	remove_action('thesis_hook_custom_template', 'thesis_custom_template_sample');
	add_action('thesis_hook_custom_template', 'places_page_layout');
	function places_page_layout () {
		if (is_page()) {
			global $post;
			$places_template = get_post_meta($post->ID, '_places_template_swapped', true);
			if(!empty($places_template)){
				?>
					<div id="places_page_content">
						<div id="sidebars">
							<?php places_ad_column(); ?>
						</div>
						<?php thesis_content_column(); ?>
					</div>
					<?php thesis_sidebars(); ?>
				<?php
			}
		}
	}
	register_sidebar(array('name'=>'Places Ads', 'before_title'=>'<h3>', 'after_title'=>'</h3>'));
	function places_ad_column(){
	?>
		<ul class="sidebar_list">
			<?php if ( !function_exists('dynamic_sidebar') || !dynamic_sidebar('Places Ads') ){ ?>
				<li class="widget">Place ads here</li>
			<?php } ?>
		</ul>
	<?php }
?>

The function places_page_layout () confirms that the current page is using the Places Template and then inserts the ad column into the page by calling places_ad_column().

3)       Create the template placeholder file

The placeholder file has two roles:

i)                     Register the new custom template in WordPress

ii)                   Call on Thesis framework to generate the Places page

The place holder file shall be located in the folder /wp-content/themes/thesis/ and called places_template.php. The code for the file is:

<?php
	/**
	 * Template Name: Places Template
	 *
	 * A custom template for use with Thesis theme for creating pages that add a left sidebar.
	 *  DO NOT EDIT THIS FILE. Instead, use the thesis_hook_custom_template() hook in custom/places_template_functions.php
	 *
	 * @package Thesis
	 */


	thesis_html_framework();

?>

The text Template Name: Places Template is key since it informs WordPress what the new template is called. The template is now listed in the WordPress page editor.

New Template Listed

4)       Load the new template into Thesis

The files that are in place so far enable WordPress to list the new template in the page Template drop-down. However, the template code is inaccessible since has not been loaded. The loading of the template code is accomplished by piggy-backing onto the Thesis custom_functions.php file. Add the following code to the end of the file:

if (file_exists(THESIS_CUSTOM . '/places_template_functions.php')){
	include(THESIS_CUSTOM . '/places_template_functions.php');
}

5)       Override Thesis custom template handling

Thesis is not aware of the new template and therefore cannot invoke it when a Places page is opened. To remedy this, we have to add code to the file places_template_functions.php that intercepts Thesis page generation and directs it execute the new template. Add the following code to the end of places_template_functions.php before the lalst  ?> :

/* Get Thesis to invoke this template*/
 if ( !is_admin() ) {
	add_action('thesis_hook_before_content_area', 'places_page_template_swap_before_content');
	add_action('thesis_hook_after_content_area', 'places_page_template_swap_after_content');
}

function places_page_template_swap_before_content(){
	if (is_page()) {
		global $post;
		global $swapped_post;
		$page_template = get_post_meta($post->ID, '_wp_page_template', true);
		if($page_template == 'places_template.php'){
			update_post_meta($post->ID, '_wp_page_template', 'custom_template.php');
			$swap_id = time();
			update_post_meta($post->ID, '_places_template_swapped', $swap_id);
			$swapped_post = $post;
		}
		else{
			$template_swapped = get_post_meta($post->ID, '_places_template_swapped', true);
			if(!empty($template_swapped)){
				$swapped_post = $post;
			}
		}
	}
}

function places_page_template_swap_after_content(){
	if (is_page()) {
		global $swapped_post;
		if(isset($swapped_post) && is_object($swapped_post)){
			$template_swapped = get_post_meta($swapped_post->ID, '_places_template_swapped', true);
			if(!empty($template_swapped)){
				$page_template = get_post_meta($swapped_post->ID, '_wp_page_template', true);
				if($page_template == 'custom_template.php'){
					update_post_meta($swapped_post->ID, '_wp_page_template', 'places_template.php');
				}
				delete_post_meta($swapped_post->ID, '_places_template_swapped');
			}
			unset($swapped_post);
		}
	}
}

You are now able to create a page, assign it the Places Template and view it to see the Places Ads column. Putting in the actual ad content can be done in the WordPress Widgets screen (Appearance > Widgets) by placing a suitable widget onto the Places Ads sidebar.

Palces Sidebar

6)       Positioning the Places Ads column

Since you have taken over the task of laying out the page columns, you’ll find that Thesis does not position the new column automatically. You need to add CSS to handle this. In this case, adding the following code to custom.css does the trick:

/* Ad column */
div#places_page_content {
	width: 656px;
	float: left;
}
div#places_page_content div#content {
	width: 545px;
	float: right;
}
div#places_page_content div#sidebars {
	width: 95px;
	float: left;
}
/* @end */

Places Template in action

Update:

Some people who have tried the code in this tutorial report that everything works ok, but the new column doesn’t show up. The most likely cause for this is that the hook that allows Thesis to see your template is not getting called. The hook to apply is dependent on the framework (Thesis Options > Design Options > Framework Options) that you’re using for the site:

1. If you’re using the ‘Full-width framework’ then the hook used in the tutorial is the correct one: thesis_hook_before_content_area

2. For ‘Page framework’, the correct hook is thesis_hook_before_content_box so edit the code in places_template_functions.php to replace:

– thesis_hook_before_content_area with thesis_hook_before_content_box

– thesis_hook_after_content_area with thesis_hook_after_content_box

remove_action(‘thesis_hook_custom_template’, ‘thesis_custom_template_sample’);

Thesis 1.8 Note:

Thanks to Cannolo (in the comments) who allowed me access to his server, I was able to debug a peculiar problem that was afflicting some implementations of the Places custom template. It turns out that in Thesis 1.8, the call to the thesis_hook_before_content_box hook was repositioned. The consequence of this is that the template swap performed by the hook now happens too late to be of any effect. The next available hook in the chain is thesis_hook_before_html. Therefore, for those who chose to use the ‘Page framework’, apply the following modification to your code:

Edit the code in places_template_functions.php to replace:

– thesis_hook_before_content_area with thesis_hook_before_html

– thesis_hook_after_content_area with thesis_hook_after_html

remove_action(‘thesis_hook_custom_template’, ‘thesis_custom_template_sample’);