You won't get hot/live reload, but you can use grunt to automatically rebuild and restart NodeBB when you make a change.

I run it with the grunt command and looked in the watch task to understand what files are synced. I understand the limitations of not getting a full browser sync and webpack-dev-server experience. However this are some problems I am facing:

1. Grunt watches at compiled code (mostly the public folder). It is a nightmare to work in minified code, although obfuscation is not used. Even if you accomplish the task of change, you will need to go back and figure out where in the source to reflect the change. If you want to adhere to the DRY, SOLID principles, you would want to makes this changes into modules (plugins, widgets, child theme), which is a painful process at the moment. Just to make it clear, I am talking even about a small change like changing the color of a button, adding a span. Nothing even remotely advanced like I said above. Those were my target, but I wanted to start small, but I realize there is no easy way even to just learn by experimenting.

2. The docs is missing in my opinion a fundamental page that should be the very first thing a developer should find: Code organization. Here is some minimal information I could not find (although I could figure out some high level details, I will play the pure dumb card to make the point)
   2.1. What goes where and why ? What is the difference between the /src files and the /build/public files. Why is the /public folder not empty as it should normally hold only compiled code from the sources (the build process should be able to delete it and recreate it fully), are the /public/less stylesheets fundamental and that is where I make changes? What is server side code and what is client side code? From the docs, I understand that rendering can be done (and it is done) both on the server and on the client. It is a great feature, but a pain in the ass since now we are doing MVC throughout client and server. I can not simply grasp the complexity of changing a view or the choices of why a server rendering was used instead of a client one (or linking the counter parts together).
   2.2 The docs are not compatible with an open source solution and look more like the docs I write at work for my team to just have a checkbox from my supervisor (nobody want to do it, but it has to be done just to say it was done). Please consider this as constructive criticism and do not consider this as rude comment for all the developers in the community or the confounders, for which I have a great amount of respect . It is simply frustrating that this amazing forum build is shooting itself in the leg with this. A simple example of this is the fact that I can not understand from the docs even a simple operation "Create nodebb-theme-mytheme/templates ". Where to create this folder? I am pretty sure it is not in the root of the project. Again this has the same problem "your theme's /templates directory, .... You may have to create this directory". Is it /templates, public/templates, build/public/templates or all of my guesses are wrong.

3. With grunt you have to manually restart the build process as it is looking like I said before at compiled code. The docs says that you can be more efficient if you limit scope like ./nodebb build adminjs admincss tpl. But I did not find the definition of those scopes and I would be clueless on what scope to use. I could bet that they are less than 10 people that can use this feature optimally (not to mention it requires a lot of effort to plan, that just running the full build every time would save you time at the end). Again the problem also hints at 2.1, what files are covered by which build scope. What is the full list of build scopes and the architectural design choices behind them.

I don't think you want a widget here.

Widgets are reusable, customizable UI elements that you can place into specific areas in templates to add stuff to footers/headers/sidebars. These widgets areas are defined by the theme.

If you want to modify how an element of the forum looks but keep the same basic style of another theme (like Persona), then you probably want to create a child theme. This way you do not need to copy the whole Persona theme, though you certainly could do that instead.

I could have used the wrong term and widget was meant to comprise the plugin definition in the forum community. I would simply call them modules/packages in terms of programming culture. I understood that widgets are in this community referring to the Android vision of widgets that you glide on the screen in an anchor position, but still you would distribute them as nodebb-plugin-... npm packages.

The fact that you can pinpoint it to a theme change or limit it to that speaks about the fact that there is something missing in the architecture design. It is not just me who has problem in recognizing the design patterns. I can tell you that it is not just a newbie problem. There is such a high barrier at the beginning that it is impossible to begin and most people will just give up. My interest was to use a forum and I was leaning towards NodeBB. I do not wish to become a Jedi master in NodeBB just to be able to change a button from left to right, as I feel it is the case at the moment.

I am still balancing in my head the options of building from scratch a forum in Angular and writing a backend (plain development of my use case and needs without even aiming for making it a public project) or spending the same amount of effort to understand and build the themes/plugins/widgets for NodeBB. I wanted option 2 as it would benefit an open source community of users, but I simply can not find the motivation to begin (or the means). For full disclosure, I am not building this forum for a business or in any way is this related to my work. This is why I am a bit careful on how I spend my time and I kind of inclined to go for option 1, as I will at least gain some valuable experience.

This is another customization to the theme, so not a widget.

This is a pretty big change from how NodeBB usually works, and it won't be easy to implement.

I guess if I want to use the NodeBB forum, I will have to go with already available plugins and just kind of profit from the work of other people. I would have wanted to contribute, but I can not see how I would be able to start to write any code for the forum.

I don't know the context of that, but you can use any IDE or editor capable of working with JS. What environment setup are you looking for?

I replied to this in a comment to @yariplus below

@pitaj Having a branch for the production version with a similar dump output is actually a great idea. You can solve the conflicts during git merge (or PRs if there would be a tea working on this) and there should be no problem.

@pitaj said in Plugin development 2021 updated - environment and dev workflow - request:

What file exactly were you editing?

I was modifying the build/public/templates/categories.tpl file. It has this template look that I am very familiar with, even from the old days of JSP. But actually comes very close to the Angular feel of template ( {componentData} -> {{componentData}}, <!-- IF -> *ngIf , <!-- BEGIN -> *ngFor).

And when I see similar code like components.get('category/topic', 'index', topicIndex);, my mind goes and recognizes the familiar angular way of defining component properties. What differs is that there is no a Component class and everything is spread in lots of files and coming from a Typescript world, this ES5 style looks a lot like compiled code (i.e. instead of a constructor, inheritance and so on, I have define('topicSelect', ['components'], function (components) {, I need to define by hand a class methods the old-fashioned way module.exports = function (Posts) { Posts.shouldQueue = async function (uid, data))

Afterwards, I understand that NodeBB hooks are a mix of property/event binding of Angular with lifecycle events (onInit,afterViewInit,onDestroy - when I read in the docs or forum that widgets will be called only when rendered for example)

I really have no issue with compile time since I am used from Angular to wait for Typescript compilation (although starting with Angular9+ and Ivy this issue does not exist anymore). Here, if I remember correctly from what I read, everything is JS and ES5.

On top of this, there are these splits of client code between backend and frontend. I actually worked with SSR in Angular and I can understand that even there it is hard to keep this frontier clean. But here, I am simply lost because of the ES5 style combined with the plugin/widget mindset. There are also some architectural design choices that are not obvious when reading the code (and not at all documented to add). Even the fact that you have a .tpl file accompanied by a .js file with the "compiled" code for the render engine is a design choice that is easily explained and should be among the first 3-4 paragraphs in the dev docs.

A critical piece of information is the code organization, as in the layout of directories and some information on files/folder contents. Frankly, one liners like this would be more than enough: "Contains compiled code during build - DO NOT TOUCH - use source files (see X directory/file)", "In this file you find the tpl of componets X,Y,Z (inspect HTML code to see placement in page)", "This file contains the Class definition of X", "Client code for SSR related to". And some of them do not require per file definitions, if from the folder and file name you can clearly see that all of them are variations of the same directory definition.

Like you said, building a forum is hard work, and I appreciate deeply the effort and time invested in an open source forum project. I am just saying that even an advanced user can not dive in and it is very restrictive the entry barrier. With minimal effort, you would have an increase in devs in the community. I am willing and prepared to contribute, but I just can't seem to start.

I don't know why I'm explaining how those commands works, that's something you could have found on your own.

I thank you for taking the time to explain this to me. However, saying that I need to build a node module (cloned from base theme repo to integrate it a plugin for the theme) and use node resolution would have been enough. The problem is that the documentation and forum topics lead to another idea.

Npm link is a way, but I could achieve this with subprojects or use even the foolish node resolution which looks at every node_module folder all the way to your root folder (something that is not very well known about node resolution of modules), place it in the "core" of the project and it will still be used, a local npm repo instead of the npm.js official repo.

If I want to develop this using grunt, I will have to add to the watch this node module to have grunt take care of rebuilding on file changes I make in the child theme repo.

---

A quick correction:

Since a topic is only associated with one category, not with a category hierarchy, you'd need to grab the latest N topics from each of the subcategories, then sort them by timestamp, then grab the top N. So it may not be very scalable, just because of how they're stored in the DB. There are several ways around this but they'd require varying degrees of difficulty and compromise.

You can probably use a union DB operation to get a list of recent topics from multiple categories at once. That would be the optimal way of doing what you want.

---

Example 1:
...
I want to break this topic into smaller topics, i.e. a topic would be a drone video of a bridge that is built on 2nd March, followed by a topic with the results of the public auction for the last segment, a topic about how the plans did not include an overpass at X location, etc. All of this I called anonymous topics since the title is not important as they are in fact part of the same larger topic, but the focus is the content.

Example 2:
...
The same forum where you have a category of Highways and subcategories Highway B1, ... Highway B100. The category Highway should not even contain topics, but you would like to show all the updates from all subcategories (i.e. individual highways) made. Most people would like to hear about all the updates (anyway, true and impactful updates are 1-2 every day across all of the highways). In case you want to dive deeper in a particular highway you go into the respective subcategory. On top of this you would have another category named Road infrastructure that contains Highways and National Roads, and the same argument is valid that you would want to see topics (updates) here from both subsections.

Okay so there are two requests here:

1. Show a topic list for all subcategories
2. Organize categories where some can't have their own topics

I think #2 is covered by "category sections". In the ACP you can edit a category and mark it as a section. If you do so, I think this prevents people from creating topics directly under that category.

As for #1, I think it's certainly possible to add this functionality within your theme. As noted above, there are actually DBAL functions for fetching from multiple sets at once. But I'd recommend you start with just using the node APIs already provided for categories and topics, and then optimize from there once you have something working.

One more thing: the read API and write API are for external services or clients. They're not for plugins to interface with. Unfortunately the API that plugins interface with is the internal undocumented API. You'll see plugins doing things like this:

// import the NodeBB DBAL module
const db = require.main.require('./src/database');

The only way to find things in the internal API is by searching through files in src/. Creating a public documented API here is something that's been on the back burner for a long time. If you have any questions about how to accomplish things there, please ask.

This is very helpful information on how to achieve this.

I will try out first the child theme cloning later today and come back with feedback. I will focus on just simple CSS/HTML changes and see how it goes.

I should have more time during the weekend to dive in even deeper in data retrieval.