WordPress naming theme files complete guide

Features overview

This guide gives all the necessary tools to achieve th best effort-less WordPress theme customisation. Therefore it will allow you to offer a wide variety of pages and layout meanwhile a strong code mutualisation.

« THE » question to be asked on top of any theme customization :

Which file WordPress is going to use when I ask a specific page to be served?

Below you will find a list of WordPress display features allowing a contextual personnalisation (we put also the minimum core version number to have) :

• Home page
• Landing page (3.0)
• Single post
• Page (2.9)
• Single Custom Content Type (3.0)
• Category related content display (post, page, custom content type)
• Tag related content display (post, page, custom content type) (2.3, 2.9)
• Custom taxonomy related content display (post, page, custom content type) (3.0)
• Archive page (3.1)
• Authors page (3.0)
• Posts list by date
• Search results display
• 404 pages
• Attachment display (2.0)

Let’s not reinvent the wheel : WordPress Codex serves a very well done PDF document showing the detailled process followed by the core when serving a page. Furthermore, it comes with the related boolean returns function (ex : is_page()) :

File choice core process organigram

get_header(), get_footer() and get_sidebar() functions

Since core 2.7, you can provide some function argument to get_header() and get_footer(), in order to specify a name to call different headers and footers. Obvious advantage : to be albe to skin pages depending on context. 404 exemple :

if ( is_home() ) :
  get_footer('home'); // Look for footer-home.php in active theme directory
elseif ( is_404() ) :
  get_footer('404'); // Look for footer-404.php in active theme directory
else :
  get_footer();
endif;

get_sidebar() allow this since core 2.5 and work just the same : « name » argument is given when the function is called and will trigger the search for a file with a name templated : sidebar-[name].php. Difference lays here in the necessary sidebar declaration in functions.php file (via register_sidebar(), mandatory in order to add widgets via admin panel :

With and without sidebar declaration :

get_sidebar('right'); // cherchera et chargera le fichier sidebar-right.php

in sidebar-right.php :

dynamic_sidebar('my-right-sidebar'); // will load widgets added in admin panel, IF 'my-right-sidebar' has already correctly been declared in functions.php

« get_template_part » function

One step further : a core 3.0 function allow us to create some files containing code we want to mutualize.  get_template_part() « officialize » what a lot of us were doing with php directive include.

It takes 2 params, 1 slug and 1 name.

get_template_part('loop','projects'); // This call will load as an include will do it the loop-projects.php file (contained in active theme directory)

Here again, you can see the pros : bigger maintenability, bigger productivity and coherence.

2 steps ahead : display engine modification

If you needs cover a specific file choice organigram (different that the one presented above), some filters have been put in order to allow you to handle the process. They use the following template name  : [type]_template_hierarchy.

Here you have some types you can reorganize :

• single_template_hierarchy
• page_template_hierarchy
• category_template_hierarchy
• …

At last, an example: how to telle the core to look for author files sorted by role in first criteria  (in functions.php):

function author_role_template( $templates ) {
    global $role;
    // creat new search mask entry
    $new_template = array( "author-$role.php" );
    // initial order core search, contained in $template variable:
    //  - author-{nicename}.php
    //  - author-{id}.php
   //   - author.php (defaut)
    $templates = array_merge( 
        array_slice( $templates, 0, -1 ), // before
        $new_template,                    // inserted
        array_slice( $templates, -1 )     // after
    );

    return $templates;
}
add_filter( 'author_template_hierarchy', 'author_role_template' );

You know how to deal with WordPress theme files in an optimal way…  Feel free to react or to post your best pratices !