• NodeBB

    This post is for plugin developers creating hooks to change functionality of NodeBB.

    NodeBB supported a hook system since the early days of it's development. This system was built long before async/await was part of nodejs. Because of this the plugin system was built using a callback system.

    When core fired a hook it would pass it a callback, and the callback would be called with the result once all the plugins processed the parameters. Here is a sample from the callback system.

    // core 
    plugins.fireHook('filter:topics.get', { topics: topics }, function (err, result) {
        console.log(results.topics);
        //...
    });
    
    // your plugin
    myPlugin.filterTopicsGet = function (hookData, callback) {
        // do something async with topics and call callback
        somethingAsync(hookData, function (err) {
           callback(err, hookData);
        });    
    }
    

    Once promises and async/await support was widely available we switched core to use async/await. Now the same hook is fired as follows.

    // core
    const result = await plugins.fireHook('filter:topics.get', { topics: topics });
    console.log(results.topics);
    

    For backwards compatibility plugin hooks written with callback style still works, but you can use async functions in your plugins as well. The above sample would looks like this

    myPlugin.filterTopicsGet = async function (hookData) {
        // do something async with topics
        await somethingAsync(hookData);
        return hookData;
    }
    

    Starting with 1.17.0, you can also use synchronous functions if your hook isn't making any async calls. Below are 3 different ways to write hooks, they are all supported.

    // async
    myPlugin.myHook = async function (hookData) {
        // do some async call
        await somethingAsync(hookData);
        return hookData;
    };
    
    // callback-style
    myPlugin.myHook = function (hookData, callback) {
        // do some async call
        somethingAsync(hookData, function (err) {
           callback(err, hookData);
        });  
    }
    
    // sync function
    myPlugin.myHook = function (hookData) {
        // set some value on hookData
        hookData.foo = 1;
        return hookData;
    }
    

    You should not mix these styles together. For example do not return a value from the hook and call the callback at the same time. This will result in core code to execute multiple times.

    myPlugin.badHook1 = function (hookData, callback) {
        hookData.foo = 1;
        callback(null, hookData);
        return hookData;
    };
    // or
    myPlugin.badHook2 = function (hookData, callback) {
        hookData.foo = 1;
        return setImmediate(callback, null, hookData);
    };
    

    Let us know if you have any questions.


  • Hello!

    Can you explain the new standards for client-side hooks?

    Previously we used the $(window).on(..., ...) notation, and now we have the new hooks module that we can use in our "client" code (was added in 1.17.0).

    For example

    require(['hooks'], function (hooks) {
    	hooks.on('action:ajaxify.end', ({ tpl_url }) => {
            ...
            });
    });
    

    What the difference between these two ways and what should we use in our plugins?

  • NodeBB

    The hooks module has the same functionality as $(window).on() but it also allows having async filter hooks client side which was not possible with $(window).trigger/on

Suggested Topics

| |