Make template hierarchy filterable

[scribu]

Currently, we have filters for each template type: home_template, author_template etc.

The trouble is that these filters are applied on the final template path, after the template hierarchy has been traversed.

It would be useful if there was another filter applied to the actual template hierarchy array, before it was sent to locate_template().

Example

Take the author template hierarchy:

author-{nicename}.php > author-{id}.php > author.php

Say I want to add author-{role}.php before author.php.

Sure, I could use the 'author_template' filter:

function author_role_template( $old_template ) {
  // get current author's role

  $new_template = locate_template( array( "author-$role.php" ) );

  if( $new_template && 'author.php' == $old_template )
    return $new_template;

  return $old_template;
}
add_filter('author_template', 'author_role_template');

With an 'author_template_candidates' hook, I could manipulate the actual hierarchy:

function author_role_template( $templates ) {
  // get current author's role

  $new_template = array( "author-$role.php" );

  $templates = array_merge( 
    array_slice( $templates, 0, -1 ), // before
    $new_template,                    // inserted
    array_slice( $templates, -1 )     // after
  );

  return $templates;
}
add_filter('author_template_hierarchy', 'author_role_template');

This would allow me to remove author-{id}.php if I wanted, etc.

template_candidates.diff makes all get_*_template() functions call get_query_template(), which consistently applies the appropriate filters.

Related: #13265 #12877

Name the filter *_template_hierarchy

template_hierarchy.diff just renames the filter *_template_hierarchy, which seems more appropriate.

refresh

(In [15611]) Apply filters consistently in get_*_template() functions. Fixes #14310

Marked #15141 as dup.

Nacin and Koopersmith expressed concerns about this. Not necessarily about the idea, but that it didn't get any peer review or iteration. Sort of landed under the radar. get_template_part() went through a lot of revisions, for example. I'd like to give this a chance for more discussion and development before it lands in core.

(In [17214]) Revert [15611] for 3.1. Needs more time for peer review and iteration. see #14310

[17214] broke custom post type templates on wp.com.

[15611] has been in trunk for four months, which is quite a while. Pulling it during/after RC 2 stage is rather last minute, particularly since it's being reverted more out of principle than due to bugs or lack of merit.

(In [17220]) I bungled [17214]. Reverting the revert, so it can be reverted properly! see #14310

I must have blindly hit "tc" or "mc" in that original revert attempt. It doesn't revert cleanly.

And on second thought, lack of review or not, coffee2code and ryan made a good point: it's been in trunk for a while. Taking it out has already caused problems for people running RC code who wanted to make use of the new filters. Leaving it in. Final answer, Regis.

Sorry for the disturbance on this one. Mea culpa.

Per discussion with Mark and westi, while a full revert is difficult due to code churn, this filter should never have been added to core. Re-opening for consideration.

I'm not convinced about the suitability of the new hook that was added here and I don't think that this has had enough discussion for us to want to keep this and preserve backwards compatibility in the future.

I would rather that we review the need for this new hook in future and discuss it more openly rather than sneak it in as part of a re-organisation of this code.

(In [17316]) Remove this new filter as it didn't get enough discussion prior to addition.
Revisit later. See #14310.

We remembered this again whilest discussing #12877 and if we are going to try and give access to the template hierarchy then we need to have a big discussion as to why we want to change these.

Fine with me.

Duplicate: #16994

Re-opened because the original goal of this ticket wasn't achieved.

just the filter

Could someone explain to me again what's wrong with the "{$type}_template_hierarchy" filter?

Do we plan to drop the hierarchy approach altogether?

Otherwise, I don't see what the big deal is, considering we already have a "{$type}_template" filter on the next line.

Replying to scribu:

Could someone explain to me again what's wrong with the "{$type}_template_hierarchy" filter?

Anyone? I'd really love to get a filter added to the template hierarchy. Oh, the things I could do with it!

A similar suggestion: #17788

Related: #13239.

Would be useful to extend the single hierarchy, see #18859.

refresh for WP 3.6-alpha

I'm trying to recreate the template hierarchy logic on the client side with AngularJS. I want client-side templates to be picked by the Angular router based on current path and naming convention using the same rules that are used by WordPress on the server side.

The easiest way to achieve this is to get the computed array of $templates from the server side whenever the location path changes on the client side, then check which client-side template fits.

This implies that a generic filter inside get_category_template can provide the $templates array corresponding to any $type.
Unfortunately I see no alternative to this filter, and if it doesn't make it in 3.6, I will have to write a plugin that overwrites the content of wp-includes/template.php. I know this is a bad practice but there is simply no other way that I can think of.