HEAD (as well as D6) has a little known feature that theme hooks can define a 'pattern' and code calling theme() can pass an array as the $hook parameter, and this enables specific named overrides of generic theme functions. The views module makes extensive use of this (using '__' as a delimiter by convention), but other than that, few people know about it.

There are now two issues in the RTBC queue for core to take advantage of this: #588148: theme_links() is not really themeable and #634472: Menus cannot be themed differently, which is awesome, because those two issues will enable more theme control of menus and links, and because, they provide a use-case within core, so this '__' feature will become more known and more used.

But, if we're gonna use this in core, and if in core, we're settling on the '__' convention, let's make it easier to use. Instead of code having to call theme(array('links__comment', 'links'), ...), how about letting theme('links__comment', ...) work. It's not that hard for theme() to split by '__'. Also, let's not require theme hooks to register a 'pattern' key to have this default behavior work. We can still leave the 'pattern' key and the $hook=array() option for modules that need more sophistication, but if we're gonna start using the '__' convention in core, let's make using it as simple as possible.

This patch adds no performance overhead in the default case of passing $hook as a string without a '__' (look at where the new code in theme() is placed). With this patch, micro-benchmarking theme(array('links__comment', 'links')) and theme('links__comment') results in equivalent performance: each is a little slower than calling theme('links'), but relative to each other, they're the same. For more benchmarking details, see #588148: theme_links() is not really themeable.

This patch should not hold up those two use-case issues. But if this lands first, they can easily be re-rolled to use it.

CommentFileSizeAuthor
drupal.theme-patterns.patch4 KBeffulgentsia

Comments

sun’s picture

Title: Make using the '__' pattern for theme fallbacks easier » Make the '__' pattern for theme suggestions easier to use
Status: Needs review » Reviewed & tested by the community

What a frickin' awesome patch!

moshe weitzman’s picture

Yeah, well done.

Crell’s picture

I don't know why the patch is not showing up green despite it saying it's passed on all tests. On visual inspection, though, this looks great and should make it very easy to provide much easier theming. It's definitely easier than the "suggestions" array that almost no one remembers how to use. :-)

effulgentsia’s picture

I've noticed on other issues too that ever since we switched to PIFR2, patches in the issue overview don't turn green after passing: only ones in comments turn green.

sun’s picture

The CSS is just buggy, trivial fix, but no one seems to care. (and I don't have access)

Status: Reviewed & tested by the community » Needs review

Re-test of drupal.theme-patterns.patch from comment @comment was requested by webchick.

Crell’s picture

Status: Needs review » Reviewed & tested by the community

Still passes. We can haz commitz?

webchick’s picture

Status: Reviewed & tested by the community » Fixed

The DX gain from this is quite impressive (see the linked issue for more information). If effulgentsia says this doesn't adversely impact performance, then that's good enough for me.

Committed to HEAD. I'll mark the other two patches related to this 'needs work' to take advantage of this.

webchick’s picture

Status: Fixed » Needs work
Issue tags: +Needs documentation

Oops. But we need to document it in the API changes guide.

effulgentsia’s picture

Any chance of having one or both of the use-case issues land, so that I can use it/them as the example in http://drupal.org/update/modules/6/7?

effulgentsia’s picture

I documented #588148: theme_links() is not really themeable in the module upgrade guide, because I couldn't think of a way of explaining #602522: Links in renderable arrays and forms (e.g. "Operations") are not alterable without being able to contrast to the way links are usually added to a render array, and I didn't want to add incorrect information about that usual way. However, before documenting #588148: theme_links() is not really themeable in the theme upgrade guide, #634472: Menus cannot be themed differently in the theme upgrade guide, or this issue in the module upgrade guide, does it make sense to first get resolution on #678714: Unify use of theme hook / template suggestions, fix clobbering problems, and improve suggestion discovery performance, to leave more room for us to back-peddle if necessary?

effulgentsia’s picture

Status: Fixed » Closed (fixed)
Issue tags: -Needs documentation

Automatically closed -- issue fixed for 2 weeks with no activity.