First of all, install the blog comments plugin by either visiting the plugin section in the ACP and clicking on install, or programmatically via npm:

npm install nodebb-plugin-blog-comments

Activate the plugin in the ACP and reboot NodeBB. Next, install the WordPress JSON API plugin.

Open up your theme and replace the contents of /wp-content/themes/YOUR_THEME/comments.php with these lines of code.

Head over to the Blog Comments section in the ACP and select the Category ID you’d like to publish your blog content to (default is Category 1). Make sure you put the correct URL to your blog. And that’s it! :)

Lavender Theme for NodeBB

As usual, if reading isn’t really your thing just hop over to the theme’s repository and start tinkering away :)

Click through to proceed to part 1 of this guide. :)

Beginner’s Note: Use supervisor to detect changes and automatically restart NodeBB

Getting Started

First lets create a new repository for our theme, we’ll call it nodebb-theme-lavender (Yes, all official NodeBB themes will be named after towns in a certain game you’ve all played. And this one is going to be purple). Place this folder in your node_modules folder. We’ll create a theme.json file in our theme directory that will look something like this:

node_modules/nodebb-theme-lavender/theme.json

{
    "id": "nodebb-theme-lavender",
    "name": "Lavender Theme for NodeBB",
    "description": "A simple theme for NodeBB. Check out the theming guide that accompanies this work at https://burnaftercompiling.com",
    "url": "https://www.github.com/psychobunny/nodebb-theme-lavender",
    "screenshot": null,
    "templates": "templates",
    "staticDir": "static"
}

We’ll create three folders in that directory, less, static, and templates. For this theme, we’re going to loosely base it off the vanilla theme. So first order of business is to create a theme.less file in the root directory (this is the main less file that NodeBB looks for) that includes the theme.less file from the vanilla theme. You could skip this step if you’re planning on creating a brand new theme from scratch.

node_modules/nodebb-theme-lavender/theme.less

@import "../nodebb-theme-vanilla/less/vanilla";
@import "../nodebb-theme-vanilla/modules";
@import "./less/style";

Create a blank less/style.less file and we’re good to go. Head over to the themes section in the Admin Control Panel and activate your theme. You will have to restart your server at this point for the changes to take affect. (NB: Unlike plugins, if you update theme.json you’ll need to reactivate it in the ACP. We’ll fix this before 0.3.x). Voila! Congratulations….. nothing should have changed (this is a good thing). This is because we’re importing the vanilla less files and haven’t actually overridden any templates yet.

progress! *insert golf-clap.gif*

If you ran into any trouble, make sure your theme directory looks exactly like it does at this commit here.

Custom Templates

When you navigate around NodeBB, the template system lazy-loads templates from the server. So if you navigated to /category, it will attempt to load category.tpl first from your custom theme directory (the only major file that breaks this rule is home.tpl for /). Failing to find a custom template, it will revert to loading the default file found at public/templates/category.tpl.

Creating a custom template is as easy as dropping the replacement into your defined custom template directory. Start with copying header.tpl straight from the default public/templates/header.tpl into our custom templates directory.

Let’s verify that we’ve successfully overridden the customized header.tpl. Locate the <navbar> and replace its navbar-inverse class with navbar-default. You should get something that looks like this:

starting to get somewhere…

(Stuck? Your theme’s code should look exactly like it does at this commit)

Importing and Overriding Bootstrap

Alright now for the fun part, we’ll copy over BS3′s less files (direct link) into a less/bootstrap folder. In our style.less, import all the BS files like so:

@import "./bootstrap/bootstrap";

And now we’re ready to start overriding Bootstrap. If you like, you could make changes straight into the BS less files. The problem is that it makes life a bit harder when keeping up to date with newer versions of BS. So I’d recommend the only file you change in there is less/bootstrap/bootstrap.less. I went in and changed the variables.less file to point to a custom variables.less file:

@import "../variables.less";

You could copy and paste the original contents into that file and start modifying from there :) I don’t intend on turning this tutorial into a “How to create a Bootstrap theme” (there are plenty of resources available on the internet), so I’m going to cheat a bit and fast forward here. I used a variables.less from an open source BS theme called “White Plum” by divshot. Had to modify it a bit to not break with 3.0.3 but you get the picture. Head on over to the repository at this commit to find out how it looks!

heh, bet you didn’t notice I reused this screenshot

That’s a wrap.

Okay I hope that Part 1 was useful for you. As I continue working on the Lavender theme I’ll be writing notes on what to include in future tutorials. Keep an eye out on that repository, I might be experimenting around with it and trying crazy things with it that might be useful to you. In later parts to this guide, I’ll definitely cover more advanced tasks like custom modules (ex. the composer or chat window), and augmenting the plugin system to keep your theme modular and easy to update.

If you ran into any issues or would like me to cover something specific, feel free to drop by our community site or hit me up on @o9k. Good luck!

Check out the official release blog post here. Have you liked NodeBB yet on Facebook? :)

Happy New Year! New year, new NodeBB release :). Quite a few features made it in as well as a bunch of bug fixes of course. I think the ones I’m really excited about are the notification based enhancements. It’s easy to miss out on notifications if you are viewing a different tab, or have the browser minimized, so we added a couple of features to make them more prominent.

First off, we added a notification counter in the favicon:

There’s a new plugin out called Desktop Notifications which alerts you of new @mentions, replies to your threads, new chat messages, etc. even if your browser is minimized. The only other app I know of that uses the HTML5 Notifications API is Gmail.

Interestingly enough, it works on mobile as well – sends you a push notification even if your browser is running in the background. Unfortunately, it seems like mobile browser support is fairly limited for now.

Click through to see what else was added in v0.2.1 :)

Three new language packs were added – French, German, and Spanish. I can’t wait to see what other languages get added – maybe on my own free time (although I’d rather be coding in new features on my free time) I might try adding a Malay language pack!

Access control was another big request that we’ve been getting. You can finally set read/write permissions for each category in the Admin Control Panel.

The biggest and most important feature of all in this release was the implementation of a Database Abstraction Layer. It’s a pretty exciting feature that @barisusakli worked on pretty much non-stop for an entire week. As you may know, NodeBB is powered completely by Redis, which is one of the many reasons why its super lightning fast. With the DBAL, we can add support for any other database software. We’ve even added MongoDB support out of the box, if that’s your thing.

New Plugins

We’ve got 25 plugins now, which is not too bad for only having launched the plugin system two months ago. Here’s a list of the new ones that came out since our last release.

• Metro Tiles (Modern UI Inspired) [screenshot]
• Desktop Notifications like G-Mail
• Masonry Categories [screenshot]
• Forum Importer
• Keyboard Shortcuts
• RSS Feed Importer [screenshot]
• Topic Archival

I hope that we’ll have a ton more plugins to come this new year :)

p.s. Our premium hosting platform at http://www.nodebb.org is secretly out of closed BETA, so go ahead and sign up :) We’ll make an official launch announcement in the coming days, so stay tuned.

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!

So I’ve been wanting to write a NodeBB setup guide for someone with pretty much no development experience at all – potentially somebody who’s never even seen a terminal in their life. I’m hoping it will reduce the barrier of entry for those wishing to try NodeBB out.

This guide will be using Digital Ocean* – but pretty much any host that gives you shell access will do. Digital Ocean is only $5 a month, which is as cheap as it gets for a host with SSH.

*DISCLAIMER: That’s a referral link, so if you spend $10 I’ll earn as much. Will spend it on more servers of course, because you can never have enough of ‘em. Thanks! :)

So on to the fun stuff. Click through for the installation guide complete with noob-friendly screenshots. :)

Setting up your server

Register for an account at Digital Ocean and add a credit card (you won’t be able to create a server without having one on file). Once you’re done, click on “Create droplet”.

On the next screen, enter your desired hostname, ex. mynodebb. For your droplet’s size: 512MB should be more than enough for a small forum, so you can leave that intact. Then select a region where this server will be located (I chose New York 1).

Under “Select Image”, leave everything as default (ie. Ubuntu 12.04 x32). This is the operating system your server will be running. Lastly, click on the “Create Droplet” button.

Congratulations! Your server should be up and running in under a minute. Check your email; the server’s IP address and root password should have been emailed to you.

Note down your server’s IP address and root password – we’ll need them for the rest of this tutorial.

Logging into your server

On Linux / Mac

If you’re on Linux (surely you don’t need this tutorial?) or Mac, you can open a terminal window and type ssh root@<YOUR SERVER’S IP ADDRESS>

ex.

ssh root@198.199.67.89

and then enter your password when prompted.

On Windows

If you’re on Windows, download putty (direct link). Run it and you should see a configuration window. Under “Host Name (or IP Address)” paste your IP address and hit enter.

You should see a security warning window, press Yes. You will be first prompted for your username; enter root. You will then be prompted for your password (tip: right click to paste and press enter).

login as: root
root@198.199.67.89's password:

After logging in

You can change the root password now with the passwd command:

root@mynodebb:~# passwd

Setting up a new account on your server

Let’s set up an account for yourself which you can use to administer your server.

root@mynodebb:~# adduser psychobunny

You will be prompted to enter a password, and set up some optional profile information about yourself.

Finally, make this user a member of the sudo group to gain admin priviledges.

root@mynodebb:~# adduser psychobunny sudo

Now, lets logout of the root user

root@mynodebb:~# logout

Setting up the software to run NodeBB

First, login to your server using the same technique as above (See the Logging in to your server section), except replace root with your new account’s username (ie. psychobunny).

Once we’re in, we’ll make sure all our packages are up to date.

psychobunny@mynodebb:~$ sudo apt-get update

Let’s install the base software stack for NodeBB:

psychobunny@mynodebb:~$ sudo apt-get install git nodejs redis-server build-essential imagemagick

Press Y to confirm.

Let’s find out what version of Node.js was installed…

psychobunny@mynodebb:~$ node --version
v0.6.12

So NodeBB requires at least Node.js v0.8, so lets get on upgrading it.

psychobunny@mynodebb:~$ sudo apt-get install python-software-properties

Press Y to confirm. We’ll add chris-lea‘s PPA to your system.

psychobunny@mynodebb:~$ sudo add-apt-repository ppa:chris-lea/node.js

Press Enter to confirm. Let’s update Node.js now:

psychobunny@mynodebb:~$ sudo apt-get update && sudo apt-get dist-upgrade

Press Y again to confirm.

When you’re presented with some dialog boxes, just press enter to select the default option. (ie. “Keep the version that’s locally installed”).

After all that is done, lets verify that Node.js was updated to the latest version.

psychobunny@mynodebb:~$ node --version
v0.10.21

Yay! Almost there…

Setting up NodeBB

Okay we’re almost there, lets create a directory to host the NodeBB code base.

psychobunny@mynodebb:~$ mkdir mynodebb

And then lets clone the NodeBB repository into the mynodebb folder:

psychobunny@mynodebb:~$ git clone git://github.com/designcreateplay/NodeBB.git mynodebb

Enter the directory:

psychobunny@mynodebb:~$ cd mynodebb

Install NodeBB’s dependencies:

psychobunny@mynodebb:~/mynodebb$ npm install

And let’s finally set up NodeBB.

psychobunny@mynodebb:~/mynodebb$ node app --setup

You’ll be prompted with some questions. The only question you need to answer is the URL, which is http://<YOUR SERVER’S IP ADDRESS>.

URL of this installation (http://localhost) http://198.199.67.89

For the rest of the configuration questions you may press enter to select the default options. We’ll run through what the rest of these do on a later tutorial, but you safely ignore them for today.

After the server is configured, it will prompt you to create an administrator account for your NodeBB forum. Enter your username, email, and password.

Finally, we can run NodeBB:

psychobunny@mynodebb:~/mynodebb$ node app

Open your browser and navigate to http://<YOUR SERVER’S IP ADDRESS>:4567, ex. http://198.199.67.89:4567

Voila!

Developing with NodeBB

You can edit your files by connecting via FTP using software such as Filezilla. The problem is that every time you make a change to the codebase, you have to restart your server – which can get pretty annoying! To make life easier we can install supervisor, which monitors the files for you and restarts the server if it detects any changes:

psychobunny@mynodebb:~/mynodebb$ sudo npm install supervisor -g                 

Now all you have to do to run nodebb is:

psychobunny@mynodebb:~/mynodebb$ ./nodebb

Now any changes you make will force supervisor to automatically restart NodeBB for you.

Did you run into any problems while running through the install? Is there anything that you’d like me to cover on a later date? Leave a comment on the bottom and let me know! Thanks for supporting NodeBB – please head over to our Facebook page and Like us! :)

To be fair its nothing more than an example plugin to demonstrate how to add a snippet of JS/HTML to the category view’s sidebar. Hopefully in the future we can do something more cooler with that, perhaps a small editor in the ACP to modify the ad dimensions or scheme. Maybe something like this adsense generator – but a little bit more cooler looking ;)

Click through for screenshots and installation instructions.

Screenshots

Installation

You can find the adsense plugin on npm.

npm install nodebb-plugin-adsense

Sign up for AdSense, create your advertisement block and copy and paste the script straight into static/sidebar.tpl. This is more of a proof-of-concept, would love to see a more full featured addon that would allow you to add advertisements in the ACP, and perhaps change the scheme/size or rearrange blocks.

Alternatively, you can clone/fork the repo on Github

More importantly, with a few skeleton plugins for people to look at, I’m hoping we can garner some interest in it from third-party developers.

I’m happy to say that I’ve released my first NodeBB plugin on NPM. Well… it’s actually my third, but the other two are “tutorial” plugins (check them out: Sample Admin Page and Sample Static Page).

So on to the fun stuff. The Cash MOD for NodeBB is a points plugin which awards the user virtual currency every time they post. They get more points per character typed, which gives the user a bit of an incentive to write higher quality posts. It isn’t a fully featured points addon yet – for example, we ought to have an ACP panel to modify user’s points – but the basics are all in (feel like improving it? fork it! :)).

Does this mean we could see an RPG addon built for NodeBB? Perhaps a port of ADR from phpBB? Or how about an Avatar system like Nulavatar? Man, that would be pretty cool… maybe one day after NodeBB development comes to the end of the roadmap I should really take a crack at it.

Click through to see screenshots of the Cash MOD in action!

Screenshots

The Cash plugin for NodeBB is installable via npm, view source on github.

npm install nodebb-plugin-cash

If you’re interested in writing your own plugins read my previous post or head over straight to Julian’s tutorial on writing plugins.

A third party plugin for parsing BBCode by adarqui is already under development, which is pretty exciting. Hopefully we can see more NodeBB plugins from developers as time progresses.

They’ve submitted a language translation pack for NodeBB which can be found on Github. The internationalization module is still a work in progress but its great to see that people are already interested in translating our forum software to other languages.

Danke NodeCode!