felix-arntz.me

Initiative for Standard WordPress Theme Hooks

Initiative for Standard WordPress Theme Hooks

A while ago I read this post by Yoast on implementing standardized theme hooks in WordPress so that plugin developers have a unified way to insert their content into a specific theme location. The ideas Yoast included there were, in my opinion, amazing – and I immediately thought that a thing like this should be pushed forward. I also found an interesting Github repository of a thing called “Theme Hook Alliance”, but unfortunately I was not able to contact anyone there and I had the impression that it is not maintained any longer. Although discussions exist about including standardized theme hooks in WordPress Core, it currently doesn’t look like such a feature could possibly be added soon. That’s why, based on the resources mentioned above, I took some time to figure out a set of guidelines that, like I think, would vastly improve the WordPress infrastructure if people maintained this standard: The “WP Theme Standardization Panel” defines these guidelines (in the Github repository you’ll find instructions and a reference file on how to implement them). There is no file that you must necessarily include in your theme, it is just a standard you should maintain in your theme. I hope that this makes its way around so that WordPress developers start discussing about it, adding useful ideas and (best case) implementing it into their themes. And this is in no way a finished set of ideas – please take part in improving as much as there is to improve!

What is such a standard?

Alright, you certainly know what standards are. So let me try to explain it from the WordPress point of view: In fact, there are many standards that WordPress itself tells us to maintain. For example, every theme must include the ‘wp_head’ action. This allows plugin developers, but also child theme developers to add content to the website’s head section. Further examples are the ‘wp_footer’ action or the ‘get_header’ function call which automatically fires the homonymous action. There are also other kinds of standards, for example what the difference between actions and filters is – the WordPress Codex is full of standards. Well, I just mentioned actions and filters which leads us to the next important question.

Why are standardized theme hooks a required step?

First, please read this extract from the WordPress Codex:

Custom Filters differ from custom Actions because custom Actions allow you to add or remove code from existing Actions. Whereas custom Filters allow you to replace specific data (such as a variable) found within an existing Action.

And now consider the way many plugins insert their content into the WordPress theme: They use the filter ‘the_content’ to add their stuff right before or after the post content, for example social sharing buttons. While this certainly works from a developer’s perspective, it is not very coherent and it certainly does not stick to the definition from above – yet many plugins do it, even those that come straight from the creators of WordPress (take a look at the Jetpack source code, for example concerning sharing and like buttons). But why do they do it? Because there is no other way! Currently there is no standard that tells us to include an action hook after the post content, and that would be a valid use-case for standardized theme hooks. But there are more points.

Some people claim that theme hooks are not necessary at all (for example, check out this post by Justin Tadlock). While I definitely agree with him in the point that child theme developers should use templates to modify their parent themes, I am nevertheless convinced that theme hooks are required. Purists argue that themes should be responsible for the content whereas plugins should contain additional functionality, but the truth is (and every WordPress developer must have realized it) that themes and plugins interact with each other. Many plugins include functionality that should be printed out to the user, so they need a way to insert it into the theme. That’s where standardized theme hooks would help.

Plugins, however, are not the only reason that we need theme hooks. Many developers prefer modular programming, and most of them like to keep their code clean and organized, separated into different PHP classes or files. For example, when I have a class ‘Meta’ which holds all functions related to post meta, I would like to include it before or after the actual post content. This is another use-case for standardized theme hooks. Some developers even allow users to turn modules of their theme on and off individually (so that a module is only loaded if it is activated), and at this point theme hooks make even more sense.

In fact, many themes and frameworks for WordPress use theme hooks, but the problem is that they are not standardized. Plugin developers don’t necessarily know the names of these hooks, and furthermore they are not willing to adjust their plugin to a thousand different themes (which I totally understand), so theme hooks as they are currently used are only for internal use within the theme. This needs to change!

How does the WP Theme Standardization Panel fit in there?

This initiative defines standards for using theme hooks in WordPress. It is of course not an official Automattic thing, but if they do not implement it in Core, we should push forward our own standard. The guidelines in the WP Theme Standardization Panel can be read in the Github repository, I will not include them in this post. The most important thing is that it defines 10 basic hook names where each hook is used twice, one time in a ‘before’ hook and the second time in an ‘after’ hook. So if your theme should support all these, you would need to implement 20 hooks. But this just sounds weird when reading it here, please take a look at the Github repository to see how it works exactly. Feel free to tell me your opinion or if you have any improvements. These standards are fully customizable and extendable, can easily be implemented into a WordPress theme and allow plugin developers to check for their existence.

So if you are interested in standardized theme hooks, in any way, please participate in the discussion, implement these guidelines if you like, open an issue on Github if you have something to criticize – and really important for a standard, share it with your fellow WordPress developers! What is your opinion about this topic in general or about the WP Theme Standardization Panel specifically?

Posted

in

by

Felix

Tags:

Comments

  1. Justin Tadlock Avatar
    Justin Tadlock

    In my article, my claim isn’t that templates hooks are not necessary. That’s a bit of a simplification of the argument. What I claim is that we don’t need many from a plugin perspective. I believe the plugin perspective is the only legitimate case we need to consider because templating has gotten much better (still needs some improvements).

    By the way, I don’t like to call them “theme hooks” because that’s a bit broad. What we’re really talking about are theme template hooks or simply template hooks. These are hooks directly called in the theme templates.

    Plugins actually have a lot of front end hooks they can use. One problem is that not everyone knows about all the hooks. If you eliminate all of those from the needed hooks list, what you’re really left with is looking at what the majority of plugins actually need. Most of those that need additional template hooks need hooks related to the individual post area and maybe the same for comments. Even the example you gave above is related to the post area. Outside of that, there really aren’t that many hooks needed by plugin authors. Other hooks are going to be too specific for core WP, which should focus on the 80%/20% rule.

    As a plugin author, I’m all in favor in making my own life and the lives of other plugin authors easier. I just don’t see many real-world cases where a ton of extra template hooks are needed. Not to mention, adoption rates for an entire set of hooks would be rough. The adoption rate of a handful of useful hooks would probably get pushed through a little faster. I’m in favor of the standardized hooks initiative as long as there are good use cases for the proposed hooks.

    Reply
    1. Felix Arntz Avatar
      Felix Arntz

      I’m sorry if I misunderstood you there. I partly agree with you that the hooks I outlined are too many for the usual use-cases. However, I think those provided in WP Core do not cover enough possibilities. A very central idea in my opinion is actually having two hooks for each area so that you can insert content before or after whatever the theme placed in that area. Especially if you think about these hooks as a theme developer who uses the action-oriented approach for development (for example in the Genesis framework), you probably utilize all of these hooks.

      From a plugin developer’s perspective, I can indeed follow your argumentation that the hooks needed there are related to the post area. I didn’t really get what you wanted to tell me there though. Are you saying that this specific part of WP Core should be improved or not? I think it would be important to invent an alternative way of inserting new content into the post area (like sharing buttons for example), different from using the ‘the_content’ filter which should only be used to modify the actual content. Using action hooks here would furthermore allow people to separate this additional stuff from the post content, for example if it should be embedded in an HTML5 header or footer tag, instead of attaching it to the content directly.

      Reply
      1. Justin Tadlock Avatar
        Justin Tadlock

        I’m definitely saying that this part of WP core should be improved (post-related hooks). Plugin developers need better methods than hooking into `the_content`. This was one of the central arguments of my article.

        However, I disagree with the need for “hooks [for the] theme developer who uses the action-oriented approach.” For WordPress core, I don’t see the need. Since these hooks don’t really apply to plugin developers, I’ll leave plugin devs out of the discussion of them. By and large, we’re talking about child theme development with these types of hooks. Thus, we’re talking about forcing all theme developers to implement action hooks that would have very little, if any, direct benefits for the vast majority of users. This is an extremely niche use case that would benefit communities around themes like Genesis and so on. However, they don’t really get that much benefit because they already have hooks in place. And, because you’re not going to be developing a child theme that works with multiple parents (impossible), standard hooks are irrelevant. The only real benefit here might be a slight decrease in learning curve when switching between the few (and, yes, there are very few) themes that use this type of system. However, these themes’ developers can easily get together and use a common hook system that they all can agree on (like THA, for example).

        This is why I say that the only legitimate argument for standard template hooks are for hooks that plugins would use.

        Reply
        1. Felix Arntz Avatar
          Felix Arntz

          I definitely see your point now. Talking about public plugins, I agree, additional hooks for other locations than the post area don’t make much sense.

          On one hand I would still approve standardized hooks for a faster and standardized custom development process. Just like we have to use functions like ‘wp_head’ or ‘get_header’, more standardized hooks would make it easier to adjust simple tweaks: let\’s say we have a theme and a plugin for sharing buttons, both from the WordPress repository. Now I would like to include the sharing buttons on top of my sidebar or my footer area. With standard theme hooks, I’d just removed the ‘the_content’ filter the plugin probably uses, and instead I’d hook the plugin function to the corresponding standard action. Without these hooks, I’d have to check if the theme has any custom action hook at this location, and if not, I would have to modify it in a child theme. However, I might have to copy/paste the whole file just to insert one additional line of code there which I don’t think is very efficient. Considering this, even if it’s just a slight improvement, it doesn’t take anything from you.

          On the other hand, yeah, it would be too much of a change in the WordPress guidelines since basically everyone would have to adjust their themes. If they had always used these hooks, it would be a different thing, but introducing them now… That brings me back to what you said, and when I think about the consequences of introducing standard theme hooks, I agree with you: Since they’re only valuable for niche use-cases, they’re probably not worth it.

          However, we should still keep pushing hooks for the post area. Thanks for this short discussion, you convinced me here!

          Reply
          1. Justin Tadlock Avatar
            Justin Tadlock

            Both of the examples you gave in your comment have existing hooks. At the top of the sidebar, you have get_sidebar for the template and dynamic_sidebar_before for the actual call to the widgets (I’d argue the plugin should merely use a widget in this case anyway). At the top of the footer area, there’s the get_footer hook. 🙂

            That was one of my points though: it’s not that we don’t have existing hooks; most people simply don’t know about them. I’ve also got a ticket (don’t know the ticket number offhand) that would provide some additional template hooks without theme authors having to change anything.

Leave a Reply

Your email address will not be published. Required fields are marked *