Writing Your First NodeBB Plugin

By Andrew Rodrigues in NodeBB 2 Comments

Since my last post about a month ago talking about the initial release of the NodeBB forums plugin system, we’ve had quite a few plugins written already. Now that the system is more mature, I thought I’d write a quick how-to guide for the aspiring plugin developer.

I’m going to use the NodeBB Youtube Plugin as an example – it’s a really simple addon that finds YouTube links in the post content and then embeds the Flash player inline.


Screenshot

So without further ado, lets get started. Click through to proceed to the guide. :)



Initial Setup

(Haven’t set up NodeBB yet? Head over to the NodeBB Setup Guide first.

First we navigate over to the node_modules directory and create a new folder called nodebb-plugin-youtube. This will be our plugin root directory which will house all of your plugin code, assets, css, etc.


Configuration

In your plugin root directory, create a plugin.json file with information about your plugin like so:

{
      "id": "nodebb-plugin-youtube"
    , "name": "NodeBB YouTube Plugin"
    , "description": "NodeBB Plugin that allows users to embed YouTube videos inline in their posts."
    , "url": "https://github.com/psychobunny/nodebb-plugin-youtube"
}

This data will be pulled into the Admin Control Panel, so that users will have some idea of what your plugin does.


Hello, World!

Let’s create a simple JS file to verify that it works. Let’s call it library.js

console.log('hello, world!');

And finally, we’ll add the following line into your plugin.json so that NodeBB knows what JS file to execute.

, "library": "./library.js"

Your plugin.json should now look like this:

{
      "id": "nodebb-plugin-youtube"
    , "name": "NodeBB YouTube Plugin"
    , "description": "NodeBB Plugin that allows users to embed YouTube videos inline in their posts."
    , "url": "https://github.com/psychobunny/nodebb-plugin-youtube"
    , "library": "./library.js"
}

That’s it! Now we’ll go to the admin panel plugins section (/admin/plugins) and Activate. Reboot your server and you should get a very familiar looking welcome message after NodeBB is initialized.

Congrats! You’ve built your first plugin! :) Now let’s make something more useful.


Your first Hook

At certain places in the NodeBB core, the plugin system is called by firing a hook. Plugins listen for these hooks and upon firing are able to manipulate data (via “filters”) or do something as a result of an event (“actions”). For the YouTube plugin, we will be looking for the post.parse filter.

Let’s create a parse method in our library.js that takes a string, looks for a YouTube URL via regular expression, and then replaces it with the appropriate object.

module.exports.parse = function(postContent, callback) {
    postContent = postContent.replace(/<a href="(?:https?:\/\/)?(?:www\.)?(?:youtube\.com|youtu\.be)\/(?:watch\?v=)?(.+)<\/a>/g, '<iframe class="youtube-plugin" width="640" height="360" src="http://www.youtube.com/embed/$1" frameborder="0" allowfullscreen></iframe>');
    callback(null, postContent);
};

Finally, we’ll let NodeBB know what hook we’re looking for (filter:post.parse) by adding the following into our plugin.json file.

, "hooks": [
    {
        "hook": "filter:post.parse"
        , "method": "parse"
        , "callbacked": true
    }
]

That’s it! Restart your server and we’re good to go :) Congratulations for getting this far!


Download the Example Code

For the latest version of the YouTube plugin, head over to Github and clone the repository.

plugin.json

{
      "id": "nodebb-plugin-youtube"
    , "name": "NodeBB YouTube Plugin"
    , "description": "NodeBB Plugin that allows users to embed YouTube videos inline in their posts."
    , "url": "https://github.com/psychobunny/nodebb-plugin-youtube"
    , "library": "./library.js"
    , "hooks": [
        {
            "hook": "filter:post.parse"
            , "method": "parse"
            , "callbacked": true
        }
    ]
}

library.js

module.exports.parse = function(postContent, callback) {
    postContent = postContent.replace(/<a href="(?:https?:\/\/)?(?:www\.)?(?:youtube\.com|youtu\.be)\/(?:watch\?v=)?(.+)<\/a>/g, '<iframe class="youtube-plugin" width="640" height="360" src="http://www.youtube.com/embed/$1" frameborder="0" allowfullscreen></iframe>');
    callback(null, postContent);
};


For further information on plugins (as well as list of available filter/action hooks), check out the NodeBB Plugins Wiki page. Feel free to drop us a line on the NodeBB forum, on our Github, or here on my blog if you need any assistance.

We can’t wait to see what future plugins are in store!

Comments

Related Articles.