on Tips

Quick tip: Custom template redirect in WordPress

2 comments
Improve WordPress speed
Tweet about this on TwitterShare on FacebookShare on Google+Share on LinkedInShare on RedditShare on StumbleUpon

Custom template redirect in WordPress can be quite useful when trying to load a special template by URL or make some kind of small API solution or changing the whole layout for a custom post type.

How WordPress process the request

To better understand what we are doing, here is a rather simplified explanation of normal WordPress request processing:

  1. Visitor comes to a certain URL
  2. WordPress initialization and loading of all settings occur
  3. WordPress decides which file from theme directory to load
  4. WordPress prepares the result and serves it to the visitor

Between first and second step, there is a hook template_redirect which we can use to load a custom template based on whatever conditions we want.

Actual examples of template redirect usage

I know it all looks strange so far, but here is an example (rather useless) which will show some text in a blank page. Place this code inside your theme’s functions.php file:

function templateRedirect()
{
    echo 'Template redirect is so cool!';
    exit;
}

// add our function to template_redirect hook
add_action('template_redirect', 'templateRedirect');

If you try whatever URL in your WordPress installation, you will get only Template redirect is cool! written on blank page.

Now, let’s do something useful for a change:

function templateRedirect()
{
    if (is_single()) {
        global $post;
        //check by postID
        if ($post->ID == 10) {
            include (TEMPLATEPATH . '/some-custom-template.php');
            exit;
        }
        // or check by post name or whatever
        if ($post->post_name == 'my-great-post') {
            include (TEMPLATEPATH . '/some-other-template.php');
            exit;
        }
    }
}

// add our function to template_redirect hook
add_action('template_redirect', 'templateRedirect');

Now, you can see how useful this can be. Above code will load a custom template if requested post has ID of 10 or name my-great-post

But, what if you want to load custom URL that WordPress is not aware of? You will get a 404 error.
You can do something similar to this:

function loadWordPressTemplate($template) {
    global $wp_query;
    // if we have a 404 status
    if ($wp_query->is_404) {
        // set status of 404 to false
        $wp_query->is_404 = false;
        $wp_query->is_archive = true;
    }
    / change the header to 200 OK
    header("HTTP/1.1 200 OK");
    //load our template
    include($template);
    exit;
}

function templateRedirect() {
    global $wp;
    if ($wp->request == 'some-custom-url-that-does-not-exist') {
        loadWordPressTemplate(TEMPLATEPATH . '/super-custom-template.php');
    }
}
 
add_action('template_redirect', 'templateRedirect');

I hope that these tips will help you achieve even more awesome stuff in your WordPress projects.

Do you use template_redirect in your projects? If you know some interesting use of this hook, please share it in the comments section.

Tweet about this on TwitterShare on FacebookShare on Google+Share on LinkedInShare on RedditShare on StumbleUpon



  • Hi Zvonko,

    Great post! One thing I might say is that template_include is the better hook to use in most of those examples above. It filters the absolute path of the template file.

    I use it a lot when I want a plug-in to provide a default custom post template (after checking that suitable template doesn’t already exist in the theme).

    • Thanks for the comment, Stephen.
      You can use template_include, but I saw that many people have some problems on how to hook it properly.
      I prefer template_redirect because I can use it inside a plugin for other things.