Add a hook for customizing the TSML configuration

[brotskydotcom]

(The history of this idea is in #1590.)

Different releases of TSML have set up the TSML configuration at different points in the request/response lifecycle. This makes it difficult to use one of the standard Wordpress hooks to do TSML custom configuration reliably.

I suggest that TSML add a custom hook (with do_action) that runs just after TSML has initialized its configuration but before it runs any code that affects the meeting database, and that this hook be documented. That way clients can use the hook to do their customization, and not worry about changes in lifecycle.

As part of this change, I would also suggest that the configuration instructions in the FAQ change to place all the custom configuration code in an action on the new hook. This would eliminate the need to check for the definition of the various functions, because the hook would never be invoked unless the TSML plugin was loaded (and the functions defined).

[brotskydotcom]

If the maintainers like this idea, I would be happy to submit a PR.

[joshreisner]

ok i think the history on this was we were using plugins_loaded for a long time to define our types but about 11 months ago switched to init because of some new notices that we were seeing in WordPress 6.7

sounds like the way we recommend people customize types (using functions.php) still works, but you prefer to use a code snippets plugin and had to change your config after we made that change.

the request is to create a new hook and documentation so it's clearer how to customize TSML using this plugin?

could you say more about this:

I would also suggest that the configuration instructions in the FAQ change to place all the custom configuration code in an action on the new hook

to my knowledge we don't recommend people use hooks to make customization in our FAQ - could you give a specific example of some documentation that should be changed?

[brotskydotcom]

So there are two different concerns that give rise to this request. They are separable but related:

1. The use of functions.php to customize plugin, rather than theme, behavior. This is an often-used but not recommended practice, because the functions.php file is owned by the current theme. Thus, theme upgrades or theme changes may remove the customization, although the plugin is still being used. See this article from the WordPress Codex for more background, including the option of using a functional plugin rather than functions.php for plugin customizations.
2. The timing of initialization and customization actions in the WordPress load sequence. The functions.php file is loaded at one specific point in the WordPress load sequence (during theme load), so it can only work for plugin configuration if the plugin code does its configuration before the theme loads but doesn't use that configuration until after the theme loads. The Wordpress recommendation to plugin developers who allow customization, as outlined in this article in the Wordpress developer resources, is to provide a custom hook that customizations can use to guarantee they are called at the appropriate time.

To address both of these concerns, the approach I am suggesting would be to do the following:

1. Define a custom hook, say tsml_additional_configuration, that is called by TSML as late as possible in the load sequence, essentially "just before" it uses any of its configuration.
2. Recommend that calls to the customization functions (such as tsml_custom_types) be run in a function added to this hook.
3. Document that users add their customization actions either via a functional plugin or by adding them to a non-theme file that is loaded early in the sequence (such as the wp-config.php file you mentioned in Customizing TSML via Wordpress Action Hook #1590).
4. Document how to add customizations by way of add_action and remove the (no longer needed) check that the customization functions are defined. For example, the answer to the "Can I update the type descriptions" FAQ question would become:

   Yes, you can add, update, or remove these descriptions. Adapt this example as needed and add to your wp-config.php file or as an always-loaded snippet. Using an empty string '' will unset the type.

   add_action('tsml_additional_configuration', function () {
       tsml_custom_descriptions([
           'C' => 'Special closed type description',
           'O' => '', //this type has been removed
       ]);
   });

None of the folks who have existing customizations in their functions.php files will be broken by any of these changes, but folks who follow these guidelines can be assured that their customizations will continue to work even if TSML finds it necessary to move around the first use of the customizations.

[joshreisner]

thanks for the additional detail!

to the first point, we usually recommend people use child themes to add their customizations. i don't have any experience with the snippets plugin, but i personally prefer making my changes that way we've been recommending for performance and security reasons. that said, i can appreciate the logic of using a plugin, since it means fewer files to maintain, and allows you to change themes more easily.

it sounds like it's working for you now using the init hook, even if that's not preferred. i'm looking forward to learning more about wordpress hook hygiene.

a question on your example, here's the current code for tsml_custom_descriptions:

function tsml_custom_descriptions($descriptions)
{
    add_action('init', function () use ($descriptions) {
        global $tsml_programs, $tsml_program;
        $tsml_programs[$tsml_program]['type_descriptions'] = $descriptions;
    });
}

would you keep that how it is? so the tsml_additional_configuration runs before the init hook, and the actual customizations still run during init?

[brotskydotcom]

Oh, wow, thanks for that detail about what the customization code does! Now I understand why I had to move my hook code back to plugins_loaded - my hook on init, which added a call to tsml_custom_descriptions, was just having the effect of adding a hook on init, so of course my customizations were never run (because init had already passed).

To answer your question about changing the customization code: Yes and No :).

• On the one hand, if TSML adds an explicit hook for doing customizations, then the customization functions themselves should actually perform the action when they are called, rather than deferring the action to some other hook.
• On the other hand, given that TSML is already using a well-known hook ('init') to run the customizations, there's no specific need to define a new, custom hook. Simply document that added customizations take effect on the init hook, so people should be sure to run the customization functions before the init hook runs. At that point the standard Wordpress documentation (which I suggest referring to) will explain about the various ways folks can get their code to run before the init hook does (such a child themes and snippets).

If TSML goes this second route, of just documenting the use of the 'init' hook as when customizations take effect, then there's no need to update either the customization functions or the docs/FAQ, although I strongly suggest removing all references to functions.php and instead referring to the Codex doc I cited about the various ways of adding customization code.

[anchovie91471]

@brotskydotcom Sorry, I'm a little late to the party here, but is it not best practice to use add_filter() as opposed to add_action(), were we to implement this feature?

Filters, I believe, are the preferred way to allow changes to variables whereas actions are more for changes to output.

[brotskydotcom]

Hi @anchovie91471, thanks for weighing in. I believe the main (and as-designed) difference between filters and actions is that the former transforms an input value and returns it whereas the latter acts via side-effect. Since the already-defined customization mechanism in TSML is to invoke functions that alter configuration imperatively and return no value, I believe an action is the appropriate invocation mechanism.