View category web

Using the new WordPress singular.php template with parent/child themes

If you weren’t aware, the latest version of WordPress (4.3) introduced a new template fallback, called singular.php. If you, like me, use WordPress as more of a CMS than as a blogging platform, this is a nice, albeit small, addition. It’s pretty straigtforward. From WordPress’ own documentation, the singular.php template is a fallback template used by both the posts and pages if their default templates are not present. This equates to the following hierarchy:

Single Post

The single post template file is used to render a single post. WordPress uses the following path:

  1. single-{post-type}-{slug}.php – (Since 4.4) First, WordPress looks for a template for the specific post. For example, if post type is product and the post slug is dmc-12, WordPress would look for single-product-dmc-12.php.
  2. single-{post-type}.php – If the post type is product, WordPress would look for single-product.php.
  3. single.php – WordPress then falls back to single.php.
  4. singular.php – Then it falls back to singular.php.
  5. index.php – Finally, WordPress ultimately falls back to index.php.

Page

The template file used to render a static page (page post-type). Note that unlike other post-types, page is special to WordPress and uses the following patch:

  1. custom template file – The page template assigned to the page.
  2. page-{slug}.php – If the page slug is recent-news, WordPress will look to usepage-recent-news.php.
  3. page-{id}.php – If the page ID is 6, WordPress will look to use page-6.php.
  4. page.php
  5. singular.php
  6. index.php

(This is lifted directly from WordPress’ documentation)

As you can see, singular is pretty far down the pecking order, but to have it so low, means it is actually more generic. And in a CMS situation where you want to have minimal differences between your post and your page templates, it reduces the number of templates required for your base template format. From what I can tell, there are no singular variants (e.g. singular-news.php won’t do anything and won’t be detected) so you if you want custom templates, you’re still going to do these the old way.

However, I was trying to use one on a new parent/child theme I’m working on, and found I couldn’t get the singular template in the child to work. No matter what I did, the page.php template was used and it confused me greatly. On reflection, it’s pretty obvious above the hierarchy I mentioned above, but as I had no single.php or page.php templates in my child theme, I couldn’t work out why singular.php wasn’t being detected. Of course, then I went back to my parent theme, which still relies on these two templates, so obviously, they were over-riding the template I was trying to have called. I wasn’t aware that template hierarchy was also inter-dependant between parent and child themes quite so heavily. I knew the child takes precedence over the parent, but was unaware that the hierarchy from one to the other was as equally important. Lesson learned.

It’s a small trip up, and not a particularly taxing one, but I didn’t find documentation about this and thought it might prove a stumbling block for someone just starting on theme development. Hope it helps someone else out there!