How do I create a settings page for my plugin?

julian

The Quickstart plugin has everything you need to get started, including an example of how to create a settings page for the plugin.

However, it is not readily apparent what parts of the code pertain to that ask, so this topic tries to disambiguate.

To create a settings page in the ACP, you'll want to do five things.

Create a template so you can add your form fields, etc.
Mount a route that loads that template
Have a link to that template show up in the ACP navigation
Allow settings to be saved
Access those settings from within your library.js

Create a template so you can add your form fields, etc.

In plugin-quickstart, you can see where templates are defined by checking plugin.json:

"templates": "static/templates"

Any templates you add to this directory will be merged with NodeBB's core template files, and bundled together during ./nodebb build. Any templates you define that conflict with core templates override the core template.

You'll notice a template file: static/templates/admin/plugins/quickstart.tpl

Since this is your own plugin, you'll want to rename this file to something more relevant, e.g. foobar.tpl.

Update the template as necessary to include any settings you'd like to define. Later on, we'll be using the NodeBB-provided settings module to persist settings to the database, so the only considerations for the template are:

That a <form> element exists with a corresponding className, e.g. <form role="form" class="foobar-settings">
That form fields have a name attribute (these names are the property names saved into the database)
That a save button exists. You can probably use this partial: . add it to the bottom of the template if it's not there already.

Mount a route that loads that template

To do this, you'll need to listen to the static:app.load hook (see how it is registered in plugin-quickstart, here).

We call the helper function .setupAdminPageRoute in order to mount the route:

routeHelpers.setupAdminPageRoute(router, '/admin/plugins/quickstart', [], controllers.renderAdminPage);

Have a link to that template show up in the ACP navigation

To do this, you'll need to listen to the filter:admin.header.build hook (see how it is registered in plugin-quickstart, here).

Relevant code:

plugin.addAdminNavigation = (header) => {
	header.plugins.push({
		route: '/plugins/quickstart',
		icon: 'fa-tint',
		name: 'Quickstart',
	});

	return header;
};

Allow settings to be saved

The modules property allows you to define require.js or CommonJS modules that can be automatically run by NodeBB (or imported/required via other files).

You can add one for ../admin/plugins/foobar.js.

Note: ../admin and ../client are magic keywords that allow NodeBB to determine whether a module is loaded for the ACP or for a client-side page. NodeBB will load the corresponding file based on template name, and if a method called init() exists, will execute it.

If you look inside static/lib/admin.js, you'll see the code that wires up the form and hooks into the Settings module in NodeBB.

You probably also want to change the module name too:

define('admin/plugins/foobar', [...

Access those settings from within your `library.js`

Lastly, now that the mount is routed and settings can be saved, you can retrieve them from within your library.js by directly invoking the meta module:

const { mySetting } = await meta.settings.get('foobar');

Irfan Babar

thank you for this.