5 Ways To Include Template Files In WordPress

dry 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!

18 Comments

  1. Do you have full instructions for how I can include a file into the fucntions.php as using these methods I get an “unexpected end of file” error.

    Reply
    • This error happens when your files have some mistakes elsewhere. Check it. I’m afraid there’s no examples because the code in the post actually good examples.

      Reply
  2. Is there a method for conditionally including a .php file based on the post’s template?

    Reply
  3. I’d like to set custom 401 & 404 error pages, but when I upload those .php files to the folder where 404.php is, nothing happens. What should I do? Help, please.

    Reply
  4. it’s not actually
    **include(TEMPLATEPATH . ‘template-name.php’);**
    but
    **include(TEMPLATEPATH . ‘/template-name.php’);**

    you forgot to include a forward slash…

    Reply
  5. Awesome, i am not php programmer. but this was very helpful to how to include templates in different templates

    thanks a lot

    Reply
  6. Didn’t know about get_template_part(). Thanks for this great post.

    Reply
  7. include(TEMPLATEPATH . ‘template-name.php’);

    oh, just forgot to tell you probably missed out the slash ‘/’

    cheers!

    Reply
  8. include(TEMPLATEPATH . ‘template-name.php’);

    still the perfect code for me.. :)

    thanks to show me that there are more codes!

    :)

    Reply
  9. Thanks @RILWIS. Very useful.I’ve a question that

    > I’ve 7 php files in the subfolder of my theme.
    > Now I want to use them as 7 tabs. But these 7 files have some php codes which is fetching contents from theme options.
    > I don’t want to use them as templates (such as using at the start)
    >> Is there any other way so I can connect them with wordpress without entering them in the template list and without change their default link?

    Thanks, I’m posting it with a hope of receiving a quick reply.

    Reply
  10. Hi, This is really nice to have this article. I’m looking to insert html into wordpress post, do you know the idea?

    Reply
  11. AWESOME!!

    Thank you very much for this post!

    I’ve been searching Google for a while trying to include remote php files into my functions.php file to keep my functions file cleaner & easier to follow.

    Thanks,

    Reply

Leave a Reply