If you're an advanced developer or just want the TL;DR version of this, skip to the code.

Programmatically Add a Template to a Page

One of the nicest things about WordPress is the ability to customize the look and feel of pages by applying customized page templates.

Whenever I am working on an advanced theme or an application, I often treat my pages like views and my templates like layouts.

In cases like this, I often need to programmatically create posts, pages, and other data upon theme activation. Similarly, I’ve also needed to programmatically add a template to a page during activation, as well.

This is relatively easy to do.

Get The Page

Technically, all you need in order to programmatically add a template to a page is the page ID. Given the fact that I’ve already shared how to create a page, it’ll be easier (and shorter!) to share how to get the ID of a page by its title.

It’s relatively common to have a sitemap template and it’s a best practice to name the corresponding page “Sitemap.” So, assuming that you have a page called “sitemap,” you can get easily get a reference to the page’s corresponding object by using get_page_by_title.

// Attempt to load the page by its title
$page = get_page_by_title( 'Sitemap', OBJECT, 'page' );

// If the page is null, set the ID to -1; otherwise, use the page's ID
$page_id = null == $page ? -1 : $page->ID;

Note that if the page isn’t returned, then I’m setting the $page_ID to -1.

In cases like this, I often use negative values to keep track of if variables have been properly set – this makes it much easier to program defensively and perform error logging that blindly assuming values are initialized.

This will also play a role in the context of the full function.

Update The Post Meta

It’s easy to add a template to a page once you have the page’s ID. Assuming that you have the page template properly formatted, it’s a matter of updating the post meta.

Generally speaking, post meta data is just that – it’s data that’s associated with any given post type (be it pages, posts, or any custom post type). Post meta is associated with a post by using a post’s ID, a key value (in this case, this is page template key), and a value for the key. In this case, it’s the template file.

WordPress stores a page’s template in the associated page’s post meta. This is done programmatically by using update_post_meta.

// Only set the template if it's a valid page
if( -1 != $page_id ) {
  update_post_meta( $page_id, '_wp_page_template', 'template-sitemap.php' );
} // end if

Note that the ‘_wp_page_template’ key is the key that WordPress natively uses to associate a template to a page and ‘template-sitemap.php’ is the name of the template in the project.

Obviously, this can be generalized to set any given template.

Programmatically Set a WordPress Template

This is the TL;DR version of all of the code covered in this article. It’s meant for those that want to see everything tied together or those that skipped the rest of the article.

The main difference in the function that’s below and the code that’s above is that I’ve generalized the code to accept the name of any page and the name of any template. I’ve commented the code to make this as clear as possible.

 * Attaches the specified template to the page identified by the specified name.
 * @params    $page_name        The name of the page to attach the template.
 * @params    $template_path    The template's filename (assumes .php' is specified)
 * @returns   -1 if the page does not exist; otherwise, the ID of the page.
function attach_template_to_page( $page_name, $template_file_name ) {

    // Look for the page by the specified title. Set the ID to -1 if it doesn't exist.
    // Otherwise, set it to the page's ID.
    $page = get_page_by_title( $page_name, OBJECT, 'page' );
    $page_id = null == $page ? -1 : $page->ID;

    // Only attach the template if the page exists
    if( -1 != $page_id ) {
        update_post_meta( $page_id, '_wp_page_template', $template_file_name );
    } // end if

    return $page_id;

} // end attach_template_to_page

To add a template to a page, you’d now do the following:

attach_template_to_page( 'sitemap', 'template-sitemap.php' );

Of course, you  may also want to wrap this into a conditional verifying that -1 isn’t returned, but that’s ultimately your call.

Resources In The Codex

For reference, here are the Codex articles related to some of the functions that I used above: