How to properly add a page template in wordpress?

Mastering WordPress Page Templates: A Comprehensive Guide

Learn how to properly add and utilize custom page templates in WordPress, enhancing your site's design and functionality beyond standard themes.

WordPress page templates offer a powerful way to customize the look and feel of individual pages on your website. Instead of being limited to your theme's default page layout, you can create unique designs for specific content, such as a landing page, a portfolio showcase, or a full-width layout without sidebars. This guide will walk you through the process of creating and implementing custom page templates, from basic file creation to assigning them within the WordPress admin.

Understanding WordPress Page Templates

A page template is essentially a PHP file that dictates the structure and appearance of a specific page or group of pages. When you create a custom template, you're telling WordPress to use this file instead of its default page.php or index.php for rendering content. This allows for immense flexibility, enabling you to include custom loops, integrate unique CSS/JavaScript, or even build entirely different layouts.

WordPress identifies page templates through a special comment block at the very top of the PHP file. This comment block contains the template's name, which then appears in the WordPress page editor, allowing you to select it for any page.

flowchart TD
    A[User Creates/Edits Page] --> B{Select Template?}
    B -- Yes --> C[WordPress Looks for Template File]
    C --> D{Template File Found?}
    D -- Yes --> E[Render Page using Custom Template]
    D -- No --> F[Render Page using Default Theme Template]
    B -- No --> F

WordPress Page Template Selection Workflow

Creating Your First Custom Page Template

The process begins by creating a new PHP file within your active theme's directory. It's highly recommended to do this within a child theme to prevent your changes from being overwritten during theme updates. If you don't have a child theme set up, consider creating one first.

Let's create a simple 'Full Width Page' template. This template will typically remove the sidebar and expand the main content area.

1. Step 1: Create a New PHP File

Using an FTP client or your hosting's file manager, navigate to your active theme's directory (or child theme's directory). Create a new file, for example, page-full-width.php.

2. Step 2: Add Template Header

Open the newly created page-full-width.php file and add the following code at the very top. This comment block is crucial for WordPress to recognize your template.

3. Step 3: Include WordPress Header and Footer

To ensure your template integrates correctly with your theme's styling and scripts, you'll need to include the standard WordPress header and footer files. These functions (get_header() and get_footer()) pull in your theme's header.php and footer.php files respectively.

4. Step 4: Add The Loop for Content

The WordPress Loop is how content is displayed. For a page template, you'll typically use a simple loop to fetch and display the page's title and content. This example also includes a basic container for styling.

5. Step 5: Save and Upload

Save the page-full-width.php file and upload it to your theme's root directory (or child theme's root directory).

<?php
/*
Template Name: Full Width Page
Template Post Type: page, post
*/

get_header();
?>

<div id="primary" class="content-area">
    <main id="main" class="site-main">

        <?php
        while ( have_posts() ) : the_post();

            get_template_part( 'template-parts/content', 'page' );

            // If comments are open or we have at least one comment, load up the comment template.
            if ( comments_open() || get_comments_number() ) :
                comments_template();
            endif;

        endwhile; // End of the loop.
        ?>

    </main><!-- #main -->
</div><!-- #primary -->

<?php
get_footer();
?>

Example of a basic page-full-width.php template file.

Assigning Your Custom Template to a Page

Once your template file is uploaded, you can easily assign it to any page (or post, if you specified Template Post Type: post) from the WordPress admin area.

1. Step 1: Navigate to Pages

In your WordPress admin dashboard, go to Pages > Add New or Pages > All Pages and edit an existing page.

2. Step 2: Locate Template Settings

On the right-hand sidebar of the page editor (in the 'Page Attributes' or 'Template' section, depending on your WordPress version and theme), you will find a dropdown menu labeled 'Template'.

3. Step 3: Select Your Template

Click the dropdown and select 'Full Width Page' (or whatever name you gave your template) from the list. If you don't see it, double-check your template file's header comment and ensure it's uploaded to the correct theme directory.

4. Step 4: Update/Publish Page

Save your changes by clicking 'Update' or 'Publish'. Your page will now render using your custom template.

Advanced Template Usage: Conditional Logic and Custom Fields

Page templates become even more powerful when combined with conditional logic and custom fields. You can use conditional tags to display different content based on various criteria, or integrate custom fields (using plugins like Advanced Custom Fields) to allow content editors to populate specific template sections.

For example, you might want a template that displays a large hero image only if a specific custom field is populated, or a template that changes its layout based on the page's parent.

<?php
/*
Template Name: Hero Image Page
Template Post Type: page
*/

get_header();

$hero_image = get_field('hero_image'); // Assuming ACF is used for 'hero_image' custom field
?>

<div id="primary" class="content-area">
    <main id="main" class="site-main">

        <?php if ( $hero_image ) : ?>
            <div class="hero-section" style="background-image: url('<?php echo esc_url($hero_image['url']); ?>');">
                <h1><?php the_title(); ?></h1>
            </div>
        <?php endif; ?>

        <?php
        while ( have_posts() ) : the_post();

            get_template_part( 'template-parts/content', 'page' );

            if ( comments_open() || get_comments_number() ) :
                comments_template();
            endif;

        endwhile; // End of the loop.
        ?>

    </main><!-- #main -->
</div><!-- #primary -->

<?php
get_footer();
?>

Example of a template using a custom field for a hero image.