设置框架

如果您需要让您的插件定制化，您可以使用 NodeBB 提供的设置框架。 If you want to make your plugin customizable you may use the Settings Framework NodeBB offers.

服务端访问

首先您需要一些默认设置，只需要像这样创建一个新对象： First you need some default settings, just create a new object for this:

  1. var defaultSettings = {
  2.         booleans: {
  3.             someBool: true,
  4.             moreBools: [false, false, true]
  5.         },
  6.         strings: {
  7.             someString: 'hello world',
  8.             multiLineString: 'some\nlong\ntext',
  9.             arrayOfStrings: ['some\nlong\ntexts', 'and another one']
  10.         },
  11.         numbers: {
  12.             multiArrayDimensions: [[42,42],[21,21]],
  13.             multiArrayDimensions2: [[42,42],[]],
  14.             justSomeNumbers: [],
  15.             oneNumber: 3,
  16.             anotherNumber: 2
  17.         },
  18.         someKeys: ['C+S+#13'] // Ctrl+Shift+Enter
  19.     };

Now you can use the server-side settings-module to access the saved settings like this:

  1. var Settings = module.parent.require('./settings');
  2. var mySettings = new Settings('myPlugin', '0.1', defaultSettings, function() {
  3.     // the settings are ready and can accessed.
  4.     console.log(mySettings === this); // true
  5.     console.log(this.get('strings.someString') === mySettings.get().strings.someString); // true
  6. });

The second parameter should change at least every time the structure of default settings changes. Because of this it’s recommended to use your plugins version.

To use the settings client-side you need to create a WebSocket that delivers the result of mySettings.get().

The mySettings-object will cache the settings, so be sure to use methods like mySettings.sync(callback) when the settings got changed from somewhere else and mySettings.persist(callback) when you finished mySettings.set(key, value) calls.

You need to create a socket-listener like following to allow the admin to initiate a synchronization with the settings stored within database:

  1. var SocketAdmin = module.parent.require('./socket.io/admin');
  2. SocketAdmin.settings.syncMyPlugin = function() {
  3.     mySettings.sync();
  4. };

If you want to add a reset-functionality you need to create another socket-listener:

  1. SocketAdmin.settings.getMyPluginDefaults = function (socket, data, callback) {
  2.     callback(null, mySettings.createDefaultWrapper());
  3. };

The methods of the mySettings object you probably want to use:

  • constructor()

  • sync([callback])

    Reloads the settings from database, overrides local changes.

  • persist([callback])

    Saves the local changes within database.

  • get([key])

    Returns the setting(s) identified by given key. If no key is provided the whole settings-object gets returned. If no such setting is saved the default value gets returned.

  • set([key, ]value)

    Sets the setting of given key to given value. Remember that it’s just a local change, you need to call persist in order to save the changes.

  • reset([callback])

    Persists the default settings.

  • getWrapper()

    Returns the local object as it would get saved within database.

  • createWrapper(version, settings)

    Creates an object like it would get saved within database containing given information and settings.

  • createDefaultWrapper()

    Creates an object like it would get saved within database containing the default settings.

Client-Side Access

The next step is making the settings available to the admin.

You need to use the hooks filter:admin.header.build (to display a link to your page within ACP) and action:app.load (to create the needed route).

Within your page you can access the client-side Settings API via

  1. require(['settings'], function (settings) {
  2.     var wrapper = $('#my_form_id');
  3.     // [1]
  4.     settings.sync('myPlugin', wrapper);
  5.     // [2]
  6. });

To make a button with the id save actually save the settings you can add the following at [2]:

  1. $('#save').click(function(event) {
  2.     event.preventDefault();
  3.     settings.persist('myPlugin', wrapper, function(){
  4.         socket.emit('admin.settings.syncMyPlugin');
  5.     });
  6. });

As said before the server-side settings-object caches the settings, so we emit a WebSocket to notify the server to synchronize the settings after they got persisted.

To use a reset-button you can add the following at [2]:

  1. $('#reset').click(function(event) {
  2.     event.preventDefault();
  3.     socket.emit('admin.settings.getMyPluginDefaults', null, function (err, data) {
  4.         settings.set('myPlugin', data, wrapper, function(){
  5.             socket.emit('admin.settings.syncMyPlugin');
  6.         });
  7.     });
  8. });

There you go, the basic structure is done. Now you need to add the form-fields.

Each field needs an attribute data-key to reference its position within the settings. The Framework does support any fields whose jQuery-object provides the value via the val() method.

The plugin to use for a field gets determined by its data-type, type or tag-name in this order.

Additionally the following plugins are registered by default:

  • array (types: div, array)

    An Array of any other fields. Uses the object within data-attributes to define the array-elements. Uses data-new to define the value of new created elements.

  • key (types: key)

    A field to input keyboard-combinations.

  • checkbox, number, select, textarea

    Handle appropriate fields.

A full list of all attributes that may influence the behavior of the default Framework:

  • data-key: the key to save/load the value within configuration-object
  • data-type: highest priority type-definition to determine what kind of element it is or which plugin to associate
  • type: normal priority type-definition
  • data-empty: if false or 0 then values that are assumed as empty turn into null. data-empty of arrays affect their child-elements
  • data-trim: if not false or 0 then values will get trimmed as defined by the elements type
  • data-split: if set and the element doesn’t belong to any plugin, it’s value will get split and joined by its value into the field

  • array-elements:

    • data-split: separator (HTML allowed) between the elements, defaults to ', '
    • data-new: value to insert into new created elements
    • data-attributes: an object to set the attributes of the child HTML-elements. tagName as special key will set the tag-name of the child HTML-elements

  • key-fields:

    • data-trim: if false or 0 then the value will get saved as string else as object providing following properties: ctrl, alt, shift, meta, code, char
    • data-split: separator between different modifiers and the key-code of the value that gets saved (only takes effect if trimming)
    • data-short: if not false or 0 then modifier-keys get saved as first uppercase character (only takes effect if trimming)

  • select:

    • data-options: an array of objects containing text and value attributes.

The methods of the settings module:

  • registerPlugin(plugin[, types])

    Registers the given plugin and associates it to the given types if any, otherwise the plugins default types will get used.

  • get()

    Returns the saved object.

  • set(hash, settings[, wrapper[, callback[, notify]]])

    Refills the fields with given settings and persists them. hash Identifies your plugins settings. settings The object to save in database (settings-wrapper if you use server-side Settings Framework). wrapper (default: ‘form’) The DOM-Element that contains all fields to fill. callback (default: null) Gets called when done. notify (default: true) Whether to display saved- and fail-notifications.

  • sync(hash[, wrapper[, callback]])

    Resets the settings to saved ones and refills the fields.

  • persist(hash[, wrapper[, callback[, notify]]])

    Reads the settings from given wrapper (default: ‘form’) and saves them within database.

For Settings 2.0 support the methods load and save are still available but not recommended.

Client-Side Example Template

An example template-file to use the same settings we already used server-side:

  1. <h1>My Plugin</h1>
  2. <hr />
  4. <form id="my_form_id">
  5.     <div class="row">
  6.         <p>
  7.             <h2>Settings</h2>
  8.             A boolean: <input type="checkbox" data-key="booleans.someBool"></input><br>
  9.             An array of checkboxes that are selected by default:
  10.             <div data-key="booleans.moreBools" data-attributes='{"data-type":"checkbox"}' data-new='true'></div><br>
  12.             A simple input-field of any common type: <input type="password" data-key="strings.someString"></input><br>
  13.             A simple textarea: <textarea data-key="strings.multiLineString"></textarea><br>
  14.             Array of textareas:
  15.             <div data-key="strings.arrayOfStrings" data-attributes='{"data-type":"textarea"}' data-new='Hello Kitty, ahem... World!'></div><br>
  17.             2D-Array of numbers that persist even when empty (but not empty rows):
  18.             <div data-key="numbers.multiArrayDimensions" data-split="<br>"
  19.                 data-attributes='{"data-type":"array","data-attributes":{"type":"number"}}' data-new='[42,21]'></div><br>
  20.             Same with persisting empty rows, but not empty numbers, if no row is given null will get saved:
  21.             <div data-key="numbers.multiArrayDimensions2" data-split="<br>" data-empty="false"
  22.                 data-attributes='{"data-type":"array","data-empty":true,"data-attributes":{"type":"number","data-empty":false}}' data-new='[42,21]'></div><br>
  23.             Array of numbers (new: 42, step: 21):
  24.             <div data-key="numbers.justSomeNumbers" data-attributes='{"data-type":"number","step":21}' data-new='42'></div><br>
  25.             Select with dynamic options:
  26.             <select data-key="numbers.oneNumber" data-options='[{"value":"2","text":"2"},{"value":"3","text":"3"}]'></select><br>
  27.             Select that loads faster:
  28.             <select data-key="numbers.anotherNumber"><br>
  29.                 <option value="2">2</option>
  30.                 <option value="3">3</option>
  31.             </select>
  33.             Array of Key-shortcuts (new: Ctrl+Shift+7):
  34.             <div data-key="someKeys" data-attributes='{"data-type":"key"}' data-new='Ctrl+Shift+#55'></div><br>
  35.         </p>
  36.     </div>
  37.     <button class="btn btn-lg btn-warning" id="reset">Reset</button>
  38.     <button class="btn btn-lg btn-primary" id="save">Save</button>
  39. </form>
  41. <script>
  42.     require(['settings'], function (settings) {
  43.         var wrapper = $('#my_form_id');
  44.         // [1]
  45.         settings.sync('myPlugin', wrapper);
  46.         $('#save').click(function(event) {
  47.             event.preventDefault();
  48.             settings.persist('myPlugin', wrapper, function(){
  49.                 socket.emit('admin.settings.syncMyPlugin');
  50.             });
  51.         });
  52.         $('#reset').click(function(event) {
  53.             event.preventDefault();
  54.             socket.emit('admin.settings.getMyPluginDefaults', null, function (err, data) {
  55.                 settings.set('myPlugin', data, wrapper, function(){
  56.                     socket.emit('admin.settings.syncMyPlugin');
  57.                 });
  58.             });
  59.         });
  60.       });
  61. </script>

Custom Settings-Elements

If you want do define your own element-structure you can create a plugin for the Settings Framework.

This allows you to use a whole object like a single field which - besides comfort in using multiple similar objects - allows you to use them within arrays.

A plugin is basically an object that contains at least an attribute types that contains an array of strings that associate DOM-elements with your plugin.

You can add a plugin at [1] using the method settings.registerPlugin.

To customize the way the associated fields get interpreted you may add the following methods to your plugin-object:

All given elements are instances of JQuery.

All methods get called within Settings-scope.

  • use()

    Gets called when the plugin gets registered.

  • [HTML-Element|JQuery] create(type, tagName, data)

    Gets called when a new element should get created (eg. by expansion of an array).

  • destruct(element)

    Gets called when the given element got removed from DOM (eg. by array-splice).

  • init(element)

    Gets called when an element should get initialized (eg. after creation).

  • [value] get(element, trim, empty)

    Gets called whenever the value of the given element is requested. trim Whether the result should get trimmed. empty Whether considered as empty values should get saved too.

  • set(element, value, trim)

    Gets called whenever the value of the given element should be set to given one. trim Whether the value is assumed as trimmed.

For further impression take a look at the default plugins.

You should also take a look at the helper-functions within Settings in order to create your own plugins. There are a few methods that take response to call the methods of other plugins when fittingly.