Ticket #12877: 12877.5.patch

wp-includes/template-loader.php

@@ -18 +18 @@
         return;
 endif;
 
+/**
+ * Locates and loads the template for current page ($wp_query).
+ * 
+ * @since 3.1.0
+ */
+function template_loader() {
 if ( defined('WP_USE_THEMES') && WP_USE_THEMES ) :
         $template = false;
         if     ( is_404()            && $template = get_404_template()            ) :
@@ -40 +46 @@
                 $template = get_index_template();
         endif;
         if ( $template = apply_filters( 'template_include', $template ) )
-                include( $template );
+                load_template( $template );
         return;
 endif;
+}
 
+update_template_hierarchy();
+template_loader();
+
 ?>

wp-includes/theme.php

@@ -1077 +1077 @@
  * @return string The template filename if one is located.
  */
 function locate_template($template_names, $load = false, $require_once = true ) {
+        $template_names = apply_filters( 'locate_template', $template_names );
+
         $located = '';
         foreach ( (array) $template_names as $template_name ) {
                 if ( !$template_name )
@@ -1121 +1123 @@
 }
 
 /**
+ * Creates a global variable that contains the template hierarchy for the current page.
+ *
+ * Calling update_template_hierarchy() will recalculate the template hierarchy for $wp_query.
+ *
+ * @uses template_loader() Calculates the template hierarchy.
+ * @since 3.1.0
+ */
+function update_template_hierarchy() {
+        global $wp_template_hierarchy;
+        
+        add_filter('locate_template', '_record_template_hierarchy');
+        add_filter('template_include', '__return_false');
+        $wp_template_hierarchy = array();
+        template_loader();
+        remove_filter('locate_template', '_record_template_hierarchy');
+        remove_filter('template_include', '__return_false');
+        $wp_template_hierarchy = call_user_func_array('array_merge', $wp_template_hierarchy);
+}
+
+/**
+ * Returns the template hierarchy for the current page.
+ *
+ * @since 3.1.0
+ * 
+ * @return array
+ */
+function get_template_hierarchy() {
+        global $wp_template_hierarchy;
+        return $wp_template_hierarchy;
+}
+
+/**
+ * Private function to modify locate_template() when updating the 
+ * template hierarchy.
+ * 
+ * Records $template_names in $wp_template_hierarchy, then returns false
+ * which causes locate_template() to fail.
+ * 
+ * @since 3.1.0
+ * @access private
+ * 
+ * @param array $template_names Template files to look for in locate_template.
+ * @return array
+ */
+function _record_template_hierarchy( $template_names ) {
+        global $wp_template_hierarchy;
+        $wp_template_hierarchy[] = $template_names;
+        return false;
+}
+
+/**
  * Display localized stylesheet link element.
  *
  * @since 2.1.0

wp-includes/general-template.php

@@ -129 +129 @@
 }
 
 /**
+ * Load a template from a folder based upon the best match from the template hierarchy.
+ *
+ * Makes it easy for a theme to reuse sections of code in a easy to overload way
+ * for child themes.
+ * 
+ * Includes a template from a folder within a theme based upon the most specific
+ * match from the template hierarchy. If the folder contains no matching files
+ * then no template will be included.
+ *
+ * @uses get_template_hierarchy() To build template file names.
+ * @uses locate_template() To search for template files.
+ * @since 3.1.0
+ *
+ * @param string $folder The name of the folder to be searched.
+ * @return string The file path to the loaded file. The empty string if no file was found.
+ */
+function get_template_module( $folder ) {
+        $template_hierarchy = get_template_hierarchy();
+        $template_names = array();
+        foreach( $template_hierarchy as $template_name ) {
+                $template_names[] = $folder . '/' . $template_name;
+        }
+
+        return locate_template($template_names, true);
+}
+
+/**
  * Display search form.
  *
  * Will first attempt to locate the searchform.php file in either the child or