Correct Handling of Static Front Page and Custom Blog Posts Index Template

Recently, there have been several Themes submitted – and approved – that include a template-blog.php (or page-blog.php) custom page template, or that include a static front pageStatic Front Page A WordPress website can have a dynamic blog-like front page, or a “static front page” which is used to show customized content. Typically this is the first page you see when you visit a site url, like wordpress.org for example. template (front-page.php) that doesn’t properly account for the user configuration to display the blog posts index on the front page. In order to be approved, Theems must handle these correctly.

Themes must properly support user configuration of the front page display, as configured via Settings -> Reading, Front page displays, Front page, and Page for posts.

The “Front page displays” option correlates to get_option( ‘show_on_front’ ), and returns a value of ‘page’ (static front page) or ‘posts’ (blog posts index). Themes must account for both values, whether or not the Theme uses front-page.php. For more information, see here.

Theme support extends beyond the “Front page displays” setting, however. Themes must also properly implement support for the “Front page” and “Page for posts” settings, as defined by the Template Hierarchy. To understand the implementation, consider the user configuration. Users set up a static front page like so:

1. Create two static pages, which we’ll call “Front Page” and “Blog”
2. In Settings -> Reading, set “Front page displays” to “a static page”
3. In Settings -> Reading, set “Front page” to “Front Page”
4. In Settings -> Reading, set “Posts page” to “Blog”

In this scenario, using the Template Hierarchy, WordPress will determine what to display in the context of Front Page and Blog Posts Index.

Front Page:

• front-page.php
• Page Template Hierarchy (custom page template, page-slug.php, page-id.php, page.php, index.php)

Blog Post Index:

• Home Template Hierarchy (home.php, index.php)

That means that, according to the Template Hierarchy, the correct file to use to define a custom blog posts index is the home.php template file, and not a custom page template. In fact, when users have properly configured a static front page and assigned pages to display the site front page and the blog posts index, a custom page template is pointless. Even if the user applies the template-blog.php custom page template to the page assigned to display the blog posts index, WordPress will ignore it, because the blog posts index uses the Home template hierarchy, and not the Page template hierarchy. WordPress will look for the home.php template file, and will fall back to the index.php template file.

So, the only possible way for the user to use a template-blog.php custom paage template would be for the Theme to instruct the user to configure the site front page and blog posts index in a way other than the way that coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. defines. Forcing the user into a different configuration than the one defined by core is poor UXUX UX is an acronym for User Experience - the way the user uses the UI. Think ‘what they are doing’ and less about how they do it.. Users should not have to configure core WordPress features differently whenever they install a new Theme.

So, if a Theme incorporates a custom template for the blog posts index, it must be implemented as the home.php template file, and not as a template-blog.php custom page template. If you are reviewing a Theme, please ensure that this is part of your review. If you’re a Theme developer, please ensure that you’re instructing your users to implement static front pages (and blog posts index pages) consistently with the core implementation, and that your Theme properly implements the Template Hierarchy.

(Side note: I strongly recommend the habit of prefixing custom page templates with “template” or “tpl” or something similar, rather than “page”. Naming a custom page template ‘page-foobar.php’ will cause WordPress to use that custom page template any time the user creates a static page with the slug “foobar”. Using something else, such as ‘template-foobar.php’ or ‘tpl-foobar.php’ will prevent that from happening, and will ensure that the custom page template is only used if the user explicitly assigns the custom page template to a given static page.)

#template-hierarchy