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
