WordPress Page Templates | Theme Developer Handbook | ...

https://developer.wordpress.org/themes/template-files-section...

Theme Handbook
Browse: Home / Theme Handbook / Template Files Section / Page Template Files / Page Templates

CHAPTERS
1

Getting Started
Who Should Read
This Handbook?
What is a Theme?
WordPress
Licensing & the
GPL
Setting up a
Development
Environment
Theme
Development
Examples
2

Theme Basics
Template Files
Post Types
Organizing Theme
Files
Template
Hierarchy
Template Tags
The Loop
Theme Functions
Linking Theme
Files &

1 von 9

Page Templates
Page templates are a
specic type of template

TOPICS

le that can be applied

to a specic page or

Uses for Page

Templates

groups of pages.

Page Templates
within the Template

Since a page template is

Hierarchy

a specic type of
template le, here are

Page Templates

some distinguishing
features of page
templates:

Purpose & User

Control
File Organization of
Page Templates

Page templates
only apply to

Creating Custom
Page Templates for

pages, not to any

other content type
(like posts and

Creating a Custom

custom post
types).
Page templates
are used to
change the look
and feel of a page.
A page template
can be applied to
a single page, a

Global Use
Page Template for
One Specic Page
Using Conditional
Tags in Page
Templates
Identifying a Page
Template
Page Template
Functions

page section, or a
class of pages.

13.06.15 12:36

WordPress Page Templates | Theme Developer Handbook | ...

Directories
Including CSS &
JavaScript

https://developer.wordpress.org/themes/template-files-section...

Page templates generally have a high level of

specicity, targeting an individual page or group
of pages. For example, a page template

Conditional Tags

named page-about.php is more specic than

the template les page.php or index.php as it

Template Files Section

will only aect a page with the slug of about.

If a page template has a template name,
WordPress users editing the page have control

Post Template
Files
Page Template
Files
Page
Templates
Attachment
Template Files
Custom Post Type
Template Files
Partial and
Miscellaneous
Template Files
4

Theme Functionality
Core-Supported

over what template will be used to render the

page.

Uses for Page Templates #

Page templates display your sites dynamic content on
a page, e.g., posts, news updates, calendar events,
media les, etc. You may decide that you want your
homepage to look a specic way, that is quite dierent
to other parts of your site. Or, you may want to display
a featured image that links to a post on one part of the
page, have a list of latest posts elsewhere, and use a
custom navigation. You can use page templates to
achieve these things.
This section shows you how to build page templates
that can be selected by your users through their admin
screens.

Features
Custom

For example, you can build page templates for:

Headers
Post
Formats
Sidebars

full-width, one-column
two-column with a sidebar on the right
two-column with a sidebar on the left
three-column

Widgets
Top

Navigation Menus
Categories, Tags, &
Custom
Taxonomies
Taxonomy
Templates
Pagination
Comments

2 von 9

Page Templates within the Template

Hierarchy #
When a person browses to your website, WordPress
selects which template to use for rendering that page.
As we learned earlier in the Template Hierarchy,
WordPress looks for template les in the following

13.06.15 12:36

WordPress Page Templates | Theme Developer Handbook | ...

Media

https://developer.wordpress.org/themes/template-files-section...

order:

Featured Images &

Post
Thumbnails
Internationalization
Localization
Accessibility

1. Page Template If the page has a custom

template assigned, WordPress looks for that le
and, if found, uses it.
2. page-{slug}.php If no custom template has
been assigned, WordPress looks for and uses a
specialized template that contains the pages
slug.

Advanced Theme Topics

Child Themes
Theme Options
The Customizer
API
Theme Security
UI Best Practices
JavaScript Best
Practices
Theme Testing

3. page-{id}.php If a specialized template that

includes the pages slug is not found, WordPress
looks for and uses a specialized template named
with the pages ID.
4. page.php If a specialized template that
includes the pages ID is not found, WordPress
looks for and uses the themes default page
template.
5. index.php If no specic page templates are
assigned or found, WordPress defaults back to
using the themes index le to render pages.

Validating Your
Theme
Plugin API Hooks
6

Releasing Your Theme

There is also a WordPress-dened

Alert:
template named paged.php. It is not used
for the page post-type but rather for
displaying multiple pages of archives.

Required Theme
Files
Testing
Theme Review
Guidelines
Writing
Documentation
Submitting Your
Theme to
WordPress.org
7

Credits

Top

Page Templates Purpose & User Control

#
If you plan on making a custom page template for your
theme, you should decide a couple of things before
proceeding:
Whether the page template will be for one
specic page or for any page; and
What type of user control you want available for
the template.
Every page template that has a template name can be

3 von 9

13.06.15 12:36

WordPress Page Templates | Theme Developer Handbook | ...

https://developer.wordpress.org/themes/template-files-section...

selected by a user when they create or edit a page. The

list of available templates can be found at Pages > Add
New > Attributes > Template. Therefore, a WordPress
user can choose any page template with a template
name, which might not be your intention.
For example, if you want to have a specic template
for your About page, it might not be appropriate to
name that page template About Template as it would
be globally available to all pages (i.e. the user could
apply it to any page). Instead, create a single use
template and WordPress will render the page with the
appropriate template, whenever a user visits the
About page.
Conversely, many themes include the ability to choose
how many columns a page will have. Each of these
options is a page template that is available globally. To
give your WordPress users this global option, you will
need to create page templates for each option and
give each a template name.
Dictating whether a template is for global use vs.
singular use is achieved by the way the le is named
and whether or not is has a specic comment.
Sometimes it is appropriate to have
Note:
a template globally available even if it
appears to be a single use case. When
youre creating themes for release, it can
be hard to predict what a user will
name their pages. Portfolio pages are a
great example as not every WordPress
user will name their portfolio the same
thing or have the same page ID and yet
they may want to use that template.

Top

File Organization of Page Templates #

As discussed in Theme Files Organization WordPress
4 von 9

13.06.15 12:36

WordPress Page Templates | Theme Developer Handbook | ...

https://developer.wordpress.org/themes/template-files-section...

recognizes the subfolder page-templates. Therefore,

its a good idea to store your global page templates in
this folder to help keep them organized.
A specialized page template le
Alert:
(those created for only one time use)
cannot be in a sub-folder, nor, if using
a Child Theme, in the Parent Themes
folder.

Top

Creating Custom Page Templates for

Global Use #
Sometimes youll want a template that can be
used globally by any page, or by multiple pages. Some
developers will group their templates with a lename
prex, such as page_two-columns.php
Important! Do not use page- as
Alert:
a prex, as WordPress will interpret the
le as a specialized template, meant to
apply to only one page on your site.

For information on theme le-naming conventions and

lenames you cannot use, see reserved theme
lenames.
A quick, safe method for creating a
Tip:
new page template is to make a copy
of page.php and give the new le a
distinct lename. That way, you start o
with the HTML structure of your other
pages and you can edit the new le as
needed.

To create a global template, write an opening PHP

5 von 9

13.06.15 12:36

WordPress Page Templates | Theme Developer Handbook | ...

https://developer.wordpress.org/themes/template-files-section...

comment at the top of the le that states the

templates name.
1

<?php /* Template Name: Example Template */

Its a good idea to choose a name that describes what

the template does as the name is visible to WordPress
users when they are editing the page. For example,
you could name your template Homepage, Blog, or
Portfolio.
This example from the TwentyFourteen theme creates
a page template called Full Width Page:
1
2
3
4
5
6
7
8

<?php
/**
* Template Name: Full Width Page
*
* @package WordPress
* @subpackage Twenty_Fourteen
* @since Twenty Fourteen 1.0
*/
Once you upload the le
to your themes folder
(e.g., page-templates), go
to the Page >
Edit screen in your admin
dashboard.
On the right hand side
under attributes youll

see template. This is

where users are able to
access your global page templates.
The select list has a maximum width
Tip:
of 250px, so longer names may be cut o.

Top

Creating a Custom Page Template for

One Specific Page #

6 von 9

13.06.15 12:36

WordPress Page Templates | Theme Developer Handbook | ...

https://developer.wordpress.org/themes/template-files-section...

As mentioned in the Template Hierarchy page, you can

create a template for a specic page. To create a
template for one specic page, copy your existing
page.php le and rename it with your pages slug or
ID:
1. page-{slug}.php
2. page-{ID}.php
For example: Your About page has a slug of about and
an ID of 6. If your active themes folder has a le
named page-about.php or page-6.php, then
WordPress will automatically nd and use that le to
render the About page.
To be used, specialized page templates must be in
your themes folder (i.e. /wp-content/themes
/my-theme-name/ ).
Top

Using Conditional Tags in Page

Templates #
You can make smaller, page-specic changes
with Conditional Tags in your themes page.php le.
For instance, the below example code loads the le
header-home.php for your front page, but loads
another le (header-about.php) for your About
page, and then applies the default header.php for all
other pages.
1
2
3
4
5
6
7

if ( is_front_page() ) :
get_header( 'home' );
elseif ( is_page( 'About' ) ) :
get_header( 'about' );
else:
get_header();
endif;

You can learn more about Conditional Tags here.

Top

Identifying a Page Template #

7 von 9

13.06.15 12:36

WordPress Page Templates | Theme Developer Handbook | ...

https://developer.wordpress.org/themes/template-files-section...

If your template uses the body_class() function,

WordPress will print classes in the body tag for the
post type class name (page), the pages ID (pageid-{ID}), and the page template used. For the
default page.php, the class name generated
is page-template-default:
1

<body class="page page-id-6 page-template-default"

A specialized template (page Note:

{slug}.php or page-{ID}.php) also
gets the page-template-default class
rather than its own body class.

When using a custom page template, the

class page-template will print, along with a class
naming the specic template. For example, if your
custom page template le is named as follows:
1

<?php /* Template Name: My Custom Page */

Then then rendered HTML generated will be as

follows:
1

<body class="page page-id-6 page-template page-template

Notice the page-template-my-custompage-php class that is applied to the body tag.

Top

Page Template Functions #

These built-in WordPress functions and methods can
help you work with page templates:
get_page_template() returns the path of the
page template used to render the page.
wp_get_theme()->get_page_templates() returns
all custom page templates available to the
currently active theme
(get_page_templates() is a method of the
WP_Theme class).

8 von 9

13.06.15 12:36

WordPress Page Templates | Theme Developer Handbook | ...

https://developer.wordpress.org/themes/template-files-section...

is_page_template() returns true or false

depending on whether a custom page template
was used to render the page.
get_page_template_slug() returns the value
of custom eld
_wp_page_template (null when the value is
empty or default).If a page has been assigned
a custom template, the lename of that
template is stored as the value of a custom
eld named '_wp_page_template' (in
the wp_postmeta database table). (Custom
elds starting with an underscore do not display
in the edit screens custom elds module.)

Page Template Files

9 von 9

About

Support

Showcase

Blog

Developers

Plugins

Hosting

Get Involved

Themes

Jobs

Learn

Ideas

WordCamp

WordPress.com

WordPress.TV

Matt

BuddyPress

Privacy

bbPress

License / GPLv2

Attachment Template Files

Follow @WordPress

13.06.15 12:36