NodeBB For a Complete Beginner

AccessDenied

A quick backstory on me: I am an experienced programmer new to the concept of NodeBB. I have very limited experience with CMS type systems, as you will find out. I've been really intrigued in what Node JS has to offer specifically in tandem with Socket IO which has ultimately brought me to NodeBB. I was recently able to get NodeBB up and running successfully and starting looking to customize the platform by writing my own plugin. This is where I get entirely lost.

The issue I have is that I have literally zero idea how anything works on the back end. I have read the documentation supplied, however I feel it is still too advanced for someone with nothing to go on. I have tried downloading plugins as examples and have just ended up with more questions than answers.

What is a controller/router/etc, how do I properly build a library, how do I know what parameters are being sent with the hooks set in the plugin.json file?

I have visited the Hooks Wiki Page but all I take away are variable names for hooks with no descriptions, documentation or indications of how these hooks interact with NodeBB. How am I supposed to know how to program or utilize any of these hooks?

For reference, I have downloaded the following plugins: nodebb-plugin-quickstart and nodebb-plugin-custom-homepage in an attempt to teach myself but I feel like this is all going a mile high over my head. The more posts I read the more confused I get on how everything actually works together.

I'm frustrated because I feel like I am the only one struggling to understand the concepts and I apologize if I've missed something entirely obvious. However, if someone could help me along with getting starting in the very basics or point me in the right direction I would be in your debt.

TL;DR I'm dumb and need lowest denominator guidance on how to understand the concept of NodeBB, plugins, widgets and themes.

sanatisharif

@AccessDenied
Please support this topic, related to your issue.

Recommand: Attracting developers and end users to nodeBB

There's docs.nodebb.org for most of that information (or at least, ideally). Sadly, documentation isn't as appealing to most developers as writing code, so i...

NodeBB Community (community.nodebb.org)

frissdiegurke

@AccessDenied said:

What is a controller/router/etc, how do I properly build a library, how do I know what parameters are being sent with the hooks set in the plugin.json file?

Controller: A controller basically is meant to provide an API (mostly by exporting the features) for accessing internal procedures. I cannot say whether or not it's done strictly within NodeBB.
In case of nodebb-plugin-quickstart I doubt the word is used correctly, in general it shouldn't come in plural for just one module.
Router: It's an express.js component providing basic functionality like associating HTTP routes with functions (router.post, router.get, etc.).
Etc: You have to ask for specific clarifications, I'm not going to list everything that comes to my mind.

I have visited the Hooks Wiki Page but all I take away are variable names for hooks with no descriptions, documentation or indications of how these hooks interact with NodeBB. How am I supposed to know how to program or utilize any of these hooks?

Since NodeBB is not yet 1.0.0, those hooks have gone through a few changes within the past (this list is auto-generated). You currently have to try concluding the functionality from the name and the code they're linked to.
If you're not able to identify a hook you need, feel free to ask here (providing expectations on the hook - and context information for reasoning in best case) and the devs/community most likely will give you a hint or might introduce that new hook for you.

For reference, I have downloaded the following plugins: nodebb-plugin-quickstart and nodebb-plugin-custom-homepage in an attempt to teach myself but I feel like this is all going a mile high over my head. The more posts I read the more confused I get on how everything actually works together.

I'm frustrated because I feel like I am the only one struggling to understand the concepts and I apologize if I've missed something entirely obvious. However, if someone could help me along with getting starting in the very basics or point me in the right direction I would be in your debt.

You could give another plugin the try for learning purposes: nodebb-plugin-shortcuts Just ignore occurrences of @{...}, they're related to my development framework and get string-replaced while compiling that plugin.
To rather check the compiled result, npm install nodebb-plugin-shortcuts and check the code within your local copy (the public/scripts/ and public/static/ directories are minified, so you'd need to check those within source rather than compiled).
I think it's a good example since I've recently reworked it with focus on readability and code-(structure-)quality. Basically look at the plugin.json to see what the plugin tells NodeBB about itself. The library for example is the main server-side entry-point which has to export all methods for hooks.
To be said: The client-side structure is much more than the average plugin uses, because it's a pretty powerful client-focused plugin.

TL;DR I'm dumb and need lowest denominator guidance on how to understand the concept of NodeBB, plugins, widgets and themes.

I also recommend you to check my list of pre-requisites to ensure you've not missed the basics of the underlying dependencies.

AccessDenied

@sanatisharif Thanks for the link. I completely agree that if NodeBB wants to move forward in popularity it is going to need to adopt some form of tutorials or documentation. If at some point I eventually grasp the concepts behind NodeBB plugins and themes enough, I would be willing to write a tutorial for a beginner that has freshly installed NodeBB. However at this point I can unhesitatingly admit that nearly anyone out there is more qualified than me at the moment.

AccessDenied

@frissdiegurke Thank you for you well written response. That clears up a lot on why I'm confused - there just simply ISN'T documentation on anything. If I could ask, how did someone like yourself become familiar with the concepts behind NodeBB? Are they just intuitive or are they related to other forum/CMS style frameworks?

I appreciate you referencing a new plugin for me to take a look at. I think my biggest question at the moment is understanding the functionality of a library. Every single plugin library I've looked at is different and communicates with NodeBB differently. I'm not sure how I am supposed to properly generate a library. For instance, please reference the following:

In nodebb-plugin-shortcuts you are attaching hook functions to an exports object and completely ignore the module variable.
In nodebb-plugin-custom-homepage the entire library is wrapped in (function(module) { ... }(module)) and instead of using an exports object to define hook functions, uses a Plugin object and assoiates module.exports = Plugin at the end.
In nodebb-plugin-quickstart the library is not wrapped but uses the Plugin object and associates module.exports to the Plugin object at the end.

Which library is built correctly? I assume they are all built correctly, but how can they all be built differently and still be interpreted by NodeBB correctly? I am under the impression that NodeBB interprets the library automatically based on a specific format and then generates the functions laid out in the header for the hook actions and filters set in plugin.json, am I wrong about that? Also, how am I supposed to know what function parameters are associated to the hook events described in plugin.json? For instance in nodebb-plugin-custom-homepage three hooks are described with the following methods, defineWidgetAreas, serveHomepage, addListing. In the library, they all have different function parameters:

Plugin.serveHomepage = function(params)
Plugin.addListing = function(data, callback)
Plugin.defineWidgetAreas = function(areas, callback)

Again, I am assuming that NodeBB builds these function parameters based off of the hook events that are called.

I appreciate your help and I hope I am not being too much of a burden.

frissdiegurke

To understand that exports syntax' you need to understand the node.js module structure a bit better:

Node.js (not NodeBB, it's just node.js) gives every module (every file that gets called somewhere using require(...), in this case from inside NodeBB core) a few (very few) global variables.
The relevant ones in this case are module and exports.

They in fact are the same from the beginning of module execution module.exports === exports.
But if you want to export something else than a plain object (such as exports) you can overwrite the exports attribute of module.

module.exports = "hello world";
// module.exports !== exports
// exports is now a meaningless object, not to be used anymore

What the two latter plugins do is to overwrite that module.exports attribute with another object (it's just the decision the dev made) instead of giving the pre-defined module.exports - that can also be referenced by exports - some new attributes.

Just consider a var exports = module.exports = {}; being executed before module-initialization. exports is a nice shortcut if you don't need to overwrite the container you want to export, but only it's attributes.

Documentation link: https://nodejs.org/api/globals.html

The other point regarding parameters for hooks can (mostly(?) at least since 0.8.0 I guess) be generalized to one parameter for action hooks and two parameters for filter or static hooks.

action: function (data) { ... } - no callback since NodeBB doesn't wait for anything, actions are just to broadcast an event
filter/static: function (data, callback) { ... } - callback to notify NodeBB back when you're done computing (by convention the callback needs to be called with callback(err, result) where one of both needs to equal null)

The data is most likely an object you can check the values either within NodeBB core code or by simply console.loging them once.

@AccessDenied said:

@frissdiegurke Thank you for you well written response. That clears up a lot on why I'm confused - there just simply ISN'T documentation on anything. If I could ask, how did someone like yourself become familiar with the concepts behind NodeBB? Are they just intuitive or are they related to other forum/CMS style frameworks?

I've been into node.js (self-trained with help of brother) in first place - plain browser-side javascript mainly via userscripts and hobby pages even beforehand - and discovered NodeBB later on.
If you have some experience with any node.js application and know a few different conventions/styles (e.g. callback vs promise-based coding) you kind-of understand all node.js applications (as long they're not too bad written).
And since NodeBB is quite well-written from my point of view it isn't hard to get into it when you know the underlying language.
I've followed NodeBB since early days (not the very beginning, but 0.3.x or so), so I've become familiar with their code-base and never had problems with reverse-engineering any feature I needed to know more about. Of cause I did ask the community a few times, mostly when I thought to have an idea of improvement or I felt like sth. was missing.

You're not a burden, I'm happy to help (besides some other reasons like improving my english knowledge). Otherwise I'd not be active within this community and would just keep writing my plugins within a dark room . If I'd even bother to write the plugins then (since I mostly write them for this very same community...).

AccessDenied

@frissdiegurke Thanks again for your response. It seems my issue centers around my fundamental understanding of NodeJS rather than NodeBB. I am going to tool around using what you said and perhaps look into some further NodeJS documentation. I am planning on spending the good majority of my day attempting my own NodeBB plugin using this knowledge. If I have any further questions I will be sure to ask here. Again, I appreciate all your help and I'm sure we will be talking again soon.

jongarrison

@AccessDenied
I went through the same process as you a few months ago and I was able to find much of what I needed between these sources:

The docs: https://docs.nodebb.org/en/latest/ (google searches will often send you to out of date versions, watch the urls!)
The source: https://github.com/NodeBB/NodeBB (Having a good IDE helps with making sense of the source and doing good searches)
I got a lot of help from purchasing Webstorm IDE (https://www.jetbrains.com/webstorm/) I've also heard people here like using Sublime Text with a lot of plugins installed.
Finding any existing plugin with related functionality to what I was trying to do was very helpful. For some reason, I found the Mandrill email plugin really helpful at first (https://github.com/akhoury/nodebb-plugin-emailer-mandrill), but just dig around until you find something with functionality related to what you are trying to do.
Lastly, I'd search and ask questions here under the plugins category (https://community.nodebb.org/category/7/nodebb-plugins). I've asked a lot of newb questions and the community has been awesome.

A few more notes. When I was first interested in Javascript and Node.js about a year ago, I went through a bunch of tutorials online. I found this one to be very well done: https://github.com/workshopper/learnyounode

Also, after developing a few plugins myself, I wrote this Slush based tool for generating NodeBB plugins based on a number of questions:
https://www.npmjs.com/package/slush-nodebb-plugin

Good luck!