How to Find the Right Theme File to Edit

[CharlesClarkson]

Purpose:
Designers need to be able to find which file to edit to affect a particular part of a page. Like traveling by automobile, this can be daunting without a good map. This tutorial will aid designers in creating a map for their StudioPress themes.

Prerequisites:
You may need to know the following:

• How to edit and save a theme file.
• How to read PHP code.

How to find the right theme file to edit

If you need to change a style like a font face or the size of a margin then you need to edit a style sheet. The theme style sheet is named style.css. Some WordPress Plugins add additional styles both inline and in files. Using Firebug for Firefox will help you track down style information.

If you need to change the structure of a page then you need to edit one of the php theme files. Read on.

When WordPress first starts up it tries to determine which page is being called. It does this by asking a series of questions. The first one which is true is chosen as the winner and WordPress goes looking for the template file which has been assigned to render it. If you are familiar with the WordPress Conditional Functions you already know the questions.

As of WordPress 2.8.5 they are:

• is_robots()
• is_feed()
• is_trackback()
• is_404()
• is_search()
• is_tax()
• is_home()
• is_attachment()
• is_single()
• is_page()
• is_category()
• is_tag()
• is_author()
• is_date()
• is_archive()
• is_comments_popup()
• is_paged()

Once a question (function) returns true WordPress still doesn't know the name of the file. For example, if is_search() is true, WordPress selects from a list of files which could be used to return a search result. This new list of files is considered as part of the Template Hierarchy of files. If all these tests fail then the index.php theme file is selected.

The Template Hierarchy contains a graphical list of the template files. I won't add it to this post because it changes as WordPress is updated. You should read the whole document to get the full details. It is important to understand how the hierarchy of files works.

Extending the example, if is_search() is true then WordPress looks for the search.php theme file. If search.php is not found then WordPress uses the index.php theme file.

If is_page() is the first test that is true then WordPress will look for a page template file, like the page_fullwidth.php theme file. If no template file is found (or if this page doesn't use a template file) then WordPress looks for the page.php theme file. If page.php is not found then WordPress will use the index.php theme file.

Now you have the file that renders the page, but you still don't have the file you need to edit. Huh?

Each template file can optionally pull in other files to make the page for the browser. StudioPress themes typically use four or more files to load a page. This is a good thing for theme authors. It allows them to add navigation menus, for instance, that are the same on each page without having to repeat the same code in multiple files.

Most StudioPress theme pages are broken down like this:
typical-page-layout.jpg

To keep things exciting, the sidebar.php theme file may call other theme files, like the sidebar_left.php theme file in Lifestyle 4.0.

If you are not sure you are in the correct file, try disabling or clearing your browser's cache and add something obvious to the file you think is the correct one. Add something like this:

<h1>I am Editing Here !</h1>

If you cannot see this change you may be in the wrong file. Don't forget to remove that line.

One more example. You need to edit the logo at the top of the page. You would edit the header.php theme file. No need to go through the hierarchy unless you have added extra header.php type theme files.


Where to go from here

• Practice what you have learned. Try tracing back a page element to the file where it originated.
• Check out the Reveal Template WordPress plugin for an automated way to find the correct template file.