5 Ways To Include Template Files In WordPress

As long as you work with WordPress, you'll realize that some code is repeated itself many times, like the loop. The new Twenty Ten theme in WordPress 3.0 has put loop code in into a loop.php file to make it separated, and when it's needed, just include it into theme file. Why don't we follow that? Separating a repeatitive code into a file is a good way to organize and manage code. It keeps our code cleaner, easier to read. All these files can be put in a current theme folder or subfolder to make a good structure. This is a very popular principle in software development: Don't Repeat Yourself (DRY) or Duplication is Evil (DIE). In WordPress, there are several ways to include a template file into current file, that we'll consider in this article.

1. Traditional way with include()

The first way to include a template file into current file of course is built-in PHP instructions: include and require:

include TEMPLATEPATH . '/template-name.php';

or

include(TEMPLATEPATH . '/template-name.php');

(We can use it as PHP instruction or as function)

This method is fastest way because it does the job as simple as possible. You'll see all other methods for including are based on it (plus some additional code). But it has a small disadvantage that it doesn't automatically check if file exists.

2. load_template()

load_template() is just the WordPress version of require()! It simply includes the PHP file into current file without checking file existence. You must pass the full path to included file.

load_template(TEMPLATEPATH . '/template-name.php');

3. locate_template()

To check file existence, we can use locate_template(). This function allows us not only to retrieve file path, but also (optional) to include that file, too.

locate_template($template_names, $load);

$load is a boolean parameter, true if you want to include this file, false if you want to get file path only.

$template_names is an array of template files that will be checked. This function will look into this array, and if it found a template file that exists, it will stop the process and return or include that file. For example, if you want to include template file for download section, but you're not sure which is its name from 'download.php', 'custom-download.php' or 'mytheme-download.php', you can use locate_template to check for these 3 template files like this:

locate_template(array(
    'download.php',
    'custom-download.php',
    'mytheme-download.php'
), true);

The locate_template() also searches in parent theme folder for files, too.

The locate_template() function uses load_template() above to include files.

4. get_query_template()

get_query_template() retrieves path to file without the use of extension. For example if you want to include template-name.php file that's located in theme folder, you can use:

include(get_query_template('template-name'));

It also checks the parent template, if the file exists. get_query_template() uses locate_template() in its code.

Note that get_query_template() just returns file path. And the argument is a string for single file. That's different from locate_template() where we can retrieve file path or include it, and we can pass a list of file for searching.

There're some siblings of get_query_template() to retrieve specific template file: get_*_template, where * can be:
- index
- 404
- archive
- author
- category
- tag
- taxonomy
- date
- home
- front_page
- page
- paged
- search
- single
- attachment
- comments_popup

They can be used like this:

include(get_404_template());

// the same
include(get_query_template('404'));

5. get_template_part() in WordPress 3.0

In WordPress 3.0, there's a more powerful function to include file: get_template_part():

get_template_part($slug, $name);

This function will include file named {slug}-{name}.php. The $name is optional, and if it's empty, the function will include file named {slug}.php. You can see this is the way Twenty Ten theme uses for including loop:

get_template_part('loop'); // general loop, file 'loop.php'
get_template_part('loop', 'index'); // loop for index, file 'loop-index.php'
get_template_part('loop', 'single'); // loop for single post, file 'loop-single.php'

I have written a post that describe this function with more details and examples that you might want to read more.

The get_template_part() function uses locate_template() in its body.

All these functions are located in wp-includes/general-template.php and wp-includes/theme.php file. If you're a coder, you can read the source code to understand all behind the scene.

I have been using these methods for a while, and see it's a good way to organize my code and theme files. Looking into my theme folder now, I can easily find which code part I need and customize it without touching another files. Many WordPress themes and frameworks are using the same principle, too. And if you haven't done this, just try. You won't reget, I promise!