[Guide] Override the home page on a NodeBB

[julian]

Overriding the home page route on a NodeBB

Difficulty: Moderate-Advanced (some theming and plugin writing experience required)

The following guide teaches you how to override the index route of a NodeBB so that it points to another page, such as /recent. This is intended to be done in a custom or forked theme.

This guide specifically will overwrite the home route to load the "Recent Topics" page.

Rationale

Not everybody wants a category listing, especially smaller boards with only one "category".

Use cases

• Show the "Recent Topics" page as the home page
• On a forum with only one category, load just that category at start
• If using the static page plugin, load that page first.

Prerequisites

NodeBB v0.5.0, or a prerelease version with commits after (or equal to) this hash: https://github.com/NodeBB/NodeBB/commit/667a78902e7c9218eb4b66bb97ebbd3e423630cb

Steps

1. Make a copy of the theme you'd like to work on. For compatibility reasons, you should probably not modify the vanilla or lavender theme files, so copying them to another folder is best
2. Rename all references of the theme id to another id of your choosing.
3. If the templates/ folder does not contain a config.json file, copy one over from nodebb-theme-vanilla. Edit this file.
4. The first line in the custom_mapping block is "^\/?$": "home",, change home to recent
5. Add a new plugin hook to your plugin.json file: { "hook": "action:app.load", "method": "init" }
6. Edit your theme's main library file (that you specified in plugin.json, right?), and create a new init method (attachment 1).
7. Save the files, select your theme, restart your NodeBB.

Attachments

Attachment 1 library.js

"use strict";

var Theme = {};

Theme.init = function(app, middleware, controllers) {
	// Overwrite the existing `/` route handler to load the recent topics (in a given month) page
	app.get('/', middleware.buildHeader,  function(req, res, next) {
		req.params.term = 'month';
		controllers.categories.recent.apply(controllers.categories.recent, arguments);
	});
	app.get('/api/home', function(req, res, next) {
		req.params.term = 'month';
		controllers.categories.recent.apply(controllers.categories.recent, arguments);
	});
};

module.exports = Theme;

[A Former User]

Woohoo! Is this a better option than an nginx rewrite?

Although I couldn't get the rewrite to work...it just led to a redirect loop. So will try this, despite no plugin creation experience.

[julian]

Prior to the prerequisite commit, it was actually impossible, so this is an improvement, albeit only a slight one.

You can override the / route, to show /recent, but it doesn't accept arguments yet, so it just loads that day's posts. Would be neat for it to be able to load /category/1, but that doesn't quite work. It works! See my edit.

There are two steps to it:

1. Overriding the route itself (in the app.load hook)
2. Overriding the custom mapping for ajaxification (non cold-loads)

Edit: Hm... actually, come to think of it, maybe there is a way...

Edit 2: Yep!

Above, I overwrote the / and /api/home routes. You can do the following to "fake" a parameter being passed in, as the home route doesn't normally provide parameters.

app.get('/', middleware.buildHeader,  function(req, res, next) {
	req.params.term = 'month';
	controllers.categories.recent.apply(controllers.categories.recent, arguments);
});
app.get('/api/home', function(req, res, next) {
	req.params.term = 'month';
	controllers.categories.recent.apply(controllers.categories.recent, arguments);
});

[A Former User]

I don't suppose the ACP will ever have a "select homepage" option? I'm guessing that would be complicated to do though, since this is already.

[trevor]

Hmm, interesting. Nice tutorial @julian !

[julian]

The Viridian theme (which is perpetually a work-in-progress theme) utilises this to have the recent topics as the primary page.

[A Former User]

@julian Hmmm, the name makes it sound like a Game of Thrones character. Interest piqued...

[julian]

Hahaha, actually, with the exception of vanilla, themes created by the NodeBB team follow a certain theme...

Lavender, Viridian, ...

I guess a sample size of 2 doesn't help

[psychobunny]

I don't suppose the ACP will ever have a "select homepage" option

I imagine it would be possible to do. It's something I've been wanting to do but haven't had the time for it yet

[limitx3m]

I'm guessing this is a little dated.

Is there a way I can create my own routes and decide what nodebb features are displayed on a page? I would like to make at least a splash page that's not separate from nodebb.

[sadmulwar]

Hi,

I am using NodeBB 0.6.0 and I tried above all steps but its not working. Can any one help me out ?

Actually instead of "Recent" page I want to show "category/2/general-discussion" as my home page.

Thanks in advance!!!

[julian]

@sadmulwar The guide is for an outdated version of NodeBB, you should just try assigning the / route against the router... @baris or @psychobunny can confirm, but in your listener for static:app.load:

plugin.init = function(data, callback) {
  data.router.get('/', function(req, res) {
    // ...
  });

callback();
});

[PitaJ]

@julian

I appears the custom homepage plugin doesn't work well with ajaxify. If you ajaxify to the / route, it just goes to the categories page. However, if you cold load to /, it goes to the custom homepage. Is there a way to fix this?

Is there a hook to add possible routes to the "Home Page Route" dropdown in the ACP?

[psychobunny]

I haven't updated that plugin yet iirc, and we haven't built a hook for the ACP dropdown just yet, but its a good idea. PR?

[PitaJ]

@psychobunny

You must code in your sleep, because the hook is definitely there already