Changeset 38385

Timestamp:

08/26/2016 09:02:08 PM (8 years ago)

Author:

johnbillion

Message:

Themes: Make the template hierarchy for a given template type filterable.

This introduces a {$type}_template_hierarchy filter that allows the hierarchy of candidate template filenames for a given template type to be filtered.

This allows the hierarchy to be added to or altered completely without resorting to re-building the hierarchy from scratch within the template_include filter, which is common and prone to conflicts between plugins and prone to getting out of sync with core's hierarchy.

Fixes #14310

File:

• trunk/src/wp-includes/template.php (modified) (2 diffs)

trunk/src/wp-includes/template.php

@@ -27 +27 @@
         $templates = array("{$type}.php");
 
+    /**
+     * Filter the list of template filenames that are searched for when retrieving a template to use.
+     *
+     * The last element in the array should always be the fallback template for this query type.
+     *
+     * Possible values for `$type` include: 'index', '404', 'archive', 'author', 'category', 'tag', 'taxonomy', 'date',
+     * 'embed', home', 'front_page', 'page', 'paged', 'search', 'single', 'singular', and 'attachment'.
+     *
+     * @since 4.7.0
+     *
+     * @param array $templates A list of template candidates, in descending order of priority.
+     */
+    $templates = apply_filters( "{$type}_template_hierarchy", $templates );
+
     $template = locate_template( $templates );
 
@@ -37 +51 @@
      *
      * Possible values for `$type` include: 'index', '404', 'archive', 'author', 'category', 'tag', 'taxonomy', 'date',
-     * 'home', 'front_page', 'page', 'paged', 'search', 'single', 'singular', and 'attachment'.
+     * 'embed', home', 'front_page', 'page', 'paged', 'search', 'single', 'singular', and 'attachment'.
      *
      * @since 1.5.0