Fun with template tags: comments_template

On my last post I talked about dynamic_sidebar and some uses. It was a fun little experiment I wanted to do and share. Yes, I said experiment. That is how I learn. I read, do and then share. I know I’m not the only one that does that.

This time I dabbled with comments_template(). Yes, another one of the more common template tags. I wanted to dissect the function and see what really makes it unique. Okay, not really, I more or less wanted to look at the code and see how it gets the template file.

Core code

The code itself is about 90 lines. That is including the inline documentation. Without the inline documentation it is about 60 lines. Good to know. It means we don’t have to guess what is going on a lot. So let’s dive in shall we?

Okay, let’s break the function down, shall we?

The arguments

The first argument that is passed is the $file location. The second is whether or not to separate the comments. Simple. But what does that mean and how can we change this?

One way, of course is by passing some arguments ourselves. Let’s say we wanted to separate the comments, we would use:

<?php comments_template( '', true ); ?>

Or if we had our comment template in another location we would use:

<?php comments_tempate( '/inc/comments.php' );

That’s great if your comment template resided in the inc folder and was named comments.php. But what happens if you don’t have a comments.php file anywhere in your theme’s folder? Well, the nice part is that WordPress does account for that. The downside is that it creates a deprecated_file call. Yes, an error. If you read the following doc-block you can see why.

/**
 * @package WordPress
 * @subpackage Theme_Compat
 * @deprecated 3.0
 *
 * This file is here for Backwards compatibility with old themes and will be removed in a future version
 *
 */

I’m going to emphasize the part that really matters most:

and will be removed in a future version

Backwards compatibility is one thing that WordPress does really well; though this is one time I wish it would do it faster. At least for these files. There are a few other files but I’ll focus on this for now.

But why does it load that file if there is no comments.php file? Let’s look a little closer at what the function actually does. At least the parts that really make it load the needed file.

if ( empty($file) )
	$file = '/comments.php';

$theme_template = STYLESHEETPATH . $file;

$include = apply_filters( 'comments_template', $theme_template );
if ( file_exists( $include ) )
	require( $include );
elseif ( file_exists( TEMPLATEPATH . $file ) )
	require( TEMPLATEPATH . $file );
else // Backward compat code will be removed in a future release
	require( ABSPATH . WPINC . '/theme-compat/comments.php');

Not really much code, right? First it checks if the passed argument $file is empty and if it is it creates a simple string of '/comments.php'. Then, it creates a variable $theme_template with the constant TEMPLATEPATH and $file appended to it. Next we see a fairly familiar function apply_filters(). The filter name is comments_template.

We can then use a filter hook to change the location of our comments template. Granted we can do the same without even using the filter by simply passing it the location string to the function itself as we saw above, right?

It matters

Why am I bringing this up? I am bringing this up because the comments template file should be the place to be using wp_list_comments() as well as comment_form(). It doesn’t have to be comments.php that houses those template tags. It could be named anything you want, you just have to make sure you are loading the file properly.

Using a filter

One way is using a filter hook. As you noticed above the line:

$include = apply_filters( 'comments_template', $theme_template );

This what we can use. The code would look a little something like:

add_filter( 'comments_template', 'demo_path_to_comments_template' );
function demo_path_to_comments_template( ){
	if ( is_child_theme() && file_exists( get_stylesheet_directory() . '/inc/coms.php' ) ){
		return get_stylesheet_directory() . '/inc/coms.php';
	} else {
		return get_template_directory() . '/inc/coms.php';
	}	
}

Yes, quite a bit just for comments, right?

Using an argument

What’s super cool about using the core template tag and passing it the argument is that it will first look in the child theme ( if active ) and then the parent theme for the file you designate.

<?php comments_template( '/comments/pings.php', true ); ?>

In the above example it will first look for the pings.php file of the child theme ( if it is active ) and if that file does not exist it will load the parent file. Sort of what get_template_part() does. That is another neat little function for another post.

Seriously, it matters

I’m going to repeat this part because it bears repeating. The backwards compatibility file will one day be removed. Your users will thank you for not using the fallback file. It shouldn’t be a safety net for the theme. Besides, if you want the theme to be hosted in the repository it can’t have any errors.

By Jose

Born in El Salvador. Loves to read, write, draw, paint, build, test, typography, hike, photography, art, design, sewing, and many other things.