Template stack - Beyond parent/child theme relationships

[johnjamesjacoby]

Problem

Robust plugins (BuddyPress, bbPress, et all) are unable to break out of the parent/child restrictions that WordPress imposes on template output. For these plugins to include their own template parts, elaborate code must be written to hook into several different execution points, requiring an intimate knowledge of the inner workings of WordPress's template loading system.

---

Solution

Create a stack of template locations, and allow WordPress to transverse this array following the same STYLESHEETPATH/TEMPLATEPATH order it always has, while also enabling additional paths to be added with a priority (similar to the filters API.)

---

Details

The attached patch includes two new functions in wp-includes/template.php:

• register_template_stack()
• get_template_stack()

Register template stack is a wrapper for the 'template_stack' filter. get_template_stack() is a variation of apply_filters() that returns the array of filtered template locations.

A modification to wp-settings.php calls register_template_stack() two times, passing get_stylesheet_directory() and get_template_directory() as callbacks, to initialize the core parent/child relationship, ensuring complete backwards compatibility.

---

Result

This allows for plugins to register additional paths in the template loader hierarchy, and enables plugins that may come with their own default template parts the option of registering a fallback template location.

This works with both locate_template() and get_template_part(), and has the added benefit removing duplicate items inside of get_template_stack(), resulting in avoiding an additional file system check should the parent and child themes be the same.

Related: #20509

A usage example from start to finish would be helpful.

Reverse lookup (name to stack) and break out of both loops

Replying to scribu:

A usage example from start to finish would be helpful.

Imagine a plugin registers a custom post type 'foo' and wants to bundle templates for twentytwelve support. This plugin would:

• Call: register_theme_stack( 'my_plugin_twentytwelve_template_path', 10 );
• Now, /plugins/my-foo/twentytwelve/single-foo.php is in the stack.
• locate_template() finds a match in the plugin directory.
• Profit.

And you could control the order (parent theme, child theme, plugin) via the priority arg. Got it.

Instead of:

register_template_stack( 'get_stylesheet_directory', 10 );

why couldn't you do:

register_template_stack( get_stylesheet_directory(), 10 );

since the callback just returns a path, which needs to be computed only once.

+1 - I've used templates located im plugins several times for a variety of reasons.

+1 as well. I've built templating systems into plugins as well and this would dramatically cut down the work load.

Replying to scribu:

why couldn't you do (...) since the callback just returns a path, which needs to be computed only once.

I went the callback route because it came with the filters API; either approach would work.

Related #21062?

Pretty neat, and we drop STYLESHEETPATH and TEMPLATEPATH in the process. +1

I like this idea.

Is there really a need for the register_template_stack() wrapper function? I'd prefer to stick with add_filter(), which is self explanatory.

Replying to johnbillion:

I like this idea.

Is there really a need for the register_template_stack() wrapper function? I'd prefer to stick with add_filter(), which is self explanatory.

add_filter() alone would work. The reason to use a dedicated function is to make it API agnostic. Should we want to move it off of the filters API later, we can do so without changing the name of the function or it's parameters.

#23180 was marked as a duplicate.

Replying to johnbillion:

Is there really a need for the register_template_stack() wrapper function? I'd prefer to stick with add_filter(), which is self explanatory.

But it isn't a filter. The values of previous function aren't passed to the next function. If I understand correctly, I don't think anything is passed to the function at all.

Right now the filter API is simply a storage mechanism, which doesn't seem right.

Patch according to @scribu and @chacha102 suggestions: uses separate global instead of filters api, pass path instead of callback, added 'remove' and 'has' functions

Above patch uses way of registering locations suggested by @scribu : add_template_stack( get_template_directory(), 12 ); , stop to use filters api as suggested @chacha102 - uses $wp_template_stack global, and adds functions to remove and check for existence of template location.