Nemcio/NodeBB
1
0
Fork 0
mirror of https://github.com/NodeBB/NodeBB.git synced 2026-03-13 08:00:43 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1484 from frissdiegurke/master

Browse Source 
Settings Framework docs + slight changes
This commit is contained in:
psychobunny
2014-05-05 10:24:34 -04:00
parent d272a87c8a c4606e7009
commit be16f0dae7
4 changed files with 329 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/index.rst
View File

@@ -73,6 +73,7 @@ Plugin System
plugins/create
plugins/hooks
plugins/settings
Widgets System
--------------

306
docs/plugins/settings.rst Normal file
View File

@@ -0,0 +1,306 @@
Settings Framework
==========================
If you want to make your plugin customizable you may use the Settings Framework NodeBB offers.
Server-Side Access
------------------
First you need some default settings, just create a new object for this:
.. code:: javascript
var defaultSettings = {
booleans: {
someBool: true,
moreBools: [false, false, true]
},
strings: {
someString: 'hello world',
multiLineString: 'some\nlong\ntext',
arrayOfStrings: ['some\nlong\ntexts', 'and another one']
},
numbers: {
multiArrayDimensions: [[42,42],[21,21]],
multiArrayDimensions2: [[42,42],[]],
justSomeNumbers: [],
oneNumber: 3,
anotherNumber: 2
},
someKeys: ['C+S+#13'] // Ctrl+Shift+Enter
};
Now you can use the server-side settings-module to access the saved settings like this:
.. code:: javascript
var Settings = module.parent.require('./settings');
var mySettings = new Settings('myPlugin', '0.1', defaultSettings, function() {
// the settings are ready and can accessed.
console.log(mySettings === this); // true
console.log(this.get('someString') === mySettings.get().someString); // true
});
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:
.. code:: javascript
var SocketAdmin = module.parent.require('./socket.io/admin');
SocketAdmin.settings.syncMyPlugin = function() {
mySettings.sync();
};
If you want to add a reset-functionality you need to create another socket-listener:
.. code:: javascript
SocketAdmin.settings.getMyPluginDefaults = function (socket, data, callback) {
callback(null, mySettings.createDefaultWrapper());
};
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 :doc:`hooks <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
.. code:: javascript
require(['settings'], function (settings) {
var wrapper = $('#my_form_id');
// [1]
settings.sync('myPlugin', wrapper);
// [2]
});
To make a button with the id ``save`` actually save the settings you can add the following at ``[2]``:
.. code:: javascript
$('#save').click(function(event) {
event.preventDefault();
settings.persist('myPlugin', wrapper, function(){
socket.emit('admin.settings.syncMyPlugin');
});
});
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]``:
.. code:: javascript
$('#reset').click(function(event) {
event.preventDefault();
socket.emit('admin.settings.getMyPluginDefaults', null, function (err, data) {
settings.set('myPlugin', data, wrapper, function(){
socket.emit('admin.settings.syncMyPlugin');
});
});
});
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, 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:
.. code:: html
<h1>My Plugin</h1>
<hr />
<form id="my_form_id">
<div class="row">
<p>
<h2>Settings</h2>
A boolean: <input type="checkbox" data-key="booleans.someBool"></input><br>
An array of checkboxes that are selected by default:
<div data-key="booleans.moreBools" data-attributes='{"data-type":"checkbox"}' data-new='true'></div><br>
A simple input-field of any common type: <input type="password" data-key="strings.someString"></input><br>
A simple textarea: <textarea data-key="strings.multiLineString"></textarea><br>
Array of textareas:
<div data-key="strings.arrayOfStrings" data-attributes='{"data-type":"textarea"}' data-new='Hello Kitty, ahem... World!'></div><br>
2D-Array of numbers that persist even when empty (but not empty rows):
<div data-key="numbers.multiArrayDimensions" data-split="<br>"
data-attributes='{"data-type":"array","data-attributes":{"type":"number"}}' data-new='[42,21]'></div><br>
Same with persisting empty rows, but not empty numbers, if no row is given null will get saved:
<div data-key="numbers.multiArrayDimensions2" data-split="<br>" data-empty="false"
data-attributes='{"data-type":"array","data-empty":true,"data-attributes":{"type":"number","data-empty":false}}' data-new='[42,21]'></div><br>
Array of numbers (new: 42, step: 21):
<div data-key="numbers.justSomeNumbers" data-attributes='{"data-type":"number","step":21}' data-new='42'></div><br>
Select with dynamic options:
<select data-key="numbers.oneNumber" data-options='[{"value":"2","text":"2"},{"value":"3","text":"3"}]'></select><br>
Select that loads faster:
<select data-key="numbers.anotherNumber"><br>
<option value="2">2</option>
<option value="3">3</option>
</select>
Array of Key-shortcuts (new: Ctrl+Shift+7):
<div data-key="someKeys" data-attributes='{"data-type":"key"}' data-new='Ctrl+Shift+#55'></div><br>
</p>
</div>
<button class="btn btn-lg btn-warning" id="reset">Reset</button>
<button class="btn btn-lg btn-primary" id="save">Save</button>
</form>
<script>
require(['settings'], function (settings) {
var wrapper = $('#my_form_id');
// [1]
settings.sync('myPlugin', wrapper);
$('#save').click(function(event) {
event.preventDefault();
settings.persist('myPlugin', wrapper, function(){
socket.emit('admin.settings.syncMyPlugin');
});
});
$('#reset').click(function(event) {
event.preventDefault();
socket.emit('admin.settings.getMyPluginDefaults', null, function (err, data) {
settings.set('myPlugin', data, wrapper, function(){
socket.emit('admin.settings.syncMyPlugin');
});
});
});
});
</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 <https://github.com/designcreateplay/NodeBB/tree/master/public/src/modules/settings>`_.
You should also take a look at the helper-functions within
`Settings <https://github.com/designcreateplay/NodeBB/tree/master/public/src/modules/settings.js>`_ in order to create
your own plugins. There are a few methods that take response to call the methods of other plugins when fittingly.

103
public/src/modules/settings.js
View File

@@ -13,79 +13,6 @@ define(function () {
waitingJobs = 0,
helper;
/*
* Attributes of HTML-tags that get used by default plugins:
* + 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 hook
* + 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 input-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 {"text":"Displayed Text","value":"some_value"}-like objects
*
* The name of the HTML-tag is lowest priority type-definition
*
* Examples-HTML:
No!
<input type="checkbox" data-key="cfg1"></input><br>
Yes!
<input type="checkbox" data-key="cfg2"></input><br>
An array of checkboxes that are selected by default:
<div data-key="cfg3" data-attributes='{"data-type":"checkbox"}' data-new='true'></div><br>
A simple input-field of any common type:
<input type="password" data-key="cfg4"></input><br>
A simple textarea:
<textarea data-key="cfg5"></textarea><br>
Array of textareas:
<div data-key="cfg6" data-attributes='{"data-type":"textarea"}' data-new='Hello Kitty, ahem... World!'></div><br>
2D-Array of numbers that persist even when empty (but not empty rows):
<div data-key="cfg7" data-split="<br>" data-attributes='{"data-type":"array","data-attributes":{"type":"number"}}' data-new='[42,21]'></div><br>
Same with persisting empty rows, but not empty numbers, if no row is given null will get saved:
<div data-key="cfg8" data-split="<br>" data-empty="false" data-attributes='{"data-type":"array","data-empty":true,"data-attributes":{"type":"number","data-empty":false}}' data-new='[42,21]'></div><br>
Array of Key-shortcuts (new: Ctrl+Shift+7):
<div data-key="cfg9" data-attributes='{"data-type":"key"}' data-new='Ctrl+Shift+#55'></div><br>
Array of numbers (new: 42, step: 21):
<div data-key="cfg10" data-attributes='{"data-type":"number","step":21}' data-new='42'></div><br>
Select with dynamic options:
<select data-key="cfg11" data-options='[{"value":"2","text":"2"},{"value":"3","text":"3"}]'></select><br>
Select that loads faster:
<select data-key="cfg12"><br>
<option value="2">2</option>
<option value="3">3</option>
</select>
*
* Matching configuration:
{
cfg1: false,
cfg2: true,
cfg3: [false, false, true],
cfg4: 'hello world',
cfg5: 'some\nlong\ntext',
cfg6: ['some\nlong\ntexts', 'and another one'],
cfg7: [[]],
cfg8: [[]],
cfg9: [],
cfg10: [],
cfg11: 3,
cfg12: 2
}
*/
/**
Returns the hook of given name that matches the given type or element.
@param type The type of the element to get the matching hook for, or the element itself.
@@ -344,9 +271,9 @@ define(function () {
@param callback The callback to call when done.
*/
persistSettings: function (hash, settings, notify, callback) {
if (settings != null && settings._settings != null && typeof settings._settings !== 'string') {
if (settings != null && settings._ != null && typeof settings._ !== 'string') {
settings = helper.deepClone(settings);
settings._settings = JSON.stringify(settings._settings);
settings._ = JSON.stringify(settings._);
}
socket.emit('admin.settings.set', {
hash: hash,
@@ -380,7 +307,7 @@ define(function () {
*/
use: function (settings) {
try {
settings._settings = JSON.parse(settings._settings);
settings._ = JSON.parse(settings._);
} catch (_error) {}
Settings.cfg = settings;
}
@@ -397,33 +324,13 @@ define(function () {
@returns Object The settings.
*/
get: function () {
if (Settings.cfg != null && Settings.cfg._settings !== void 0) {
return Settings.cfg._settings;
if (Settings.cfg != null && Settings.cfg._ !== void 0) {
return Settings.cfg._;
}
return Settings.cfg;
},
/**
Registers a new plugin and calls its use-hook.
A plugin is an object containing a types-property to define its default bindings.
A plugin may also provide the following properties of type function with [return-value] (parameters):
use [void] - gets called when the Settings initializes the plugin.
init [void] (element) - gets called on page-load and every time after the create-hook.
; element: The element to initialize.
create [JQuery-Object] (type, tagName, data) - gets called when a new HTML-instance needs to get created.
; type: A string that identifies the plugin itself within this Settings-instance if set as data-type.
; tagName: The tag-name that gets requested.
; data: Additional data, plugin-dependent meaning.
destruct [void] (element) - gets called after a HTML-instance got removed from DOM
; element: The element that got removed.
set [void] (element, value, trim) - gets called when the value of the element should be set to the given value.
; element: The element to set its value.
; value: The value to set.
; trim: Whether the value is considered as trimmed.
get [value] (element, trim, empty) - gets called when the value of the given instance is needed.
; element: The element to get its value.
; trim: Whether the result should be trimmed.
; empty: Whether considered as empty values should get saved too.
All passed elements are JQuery-Objects.
@param service The plugin to register.
@param types The types to bind the plugin to.
*/

53
src/settings.js
View File

@@ -26,16 +26,16 @@ function trim(obj1, obj2) {
}
function mergeSettings(cfg, defCfg) {
if (typeof cfg._settings !== typeof defCfg || typeof defCfg !== 'object') {
return cfg._settings = defCfg;
if (typeof cfg._ !== typeof defCfg || typeof defCfg !== 'object') {
cfg._ = defCfg;
} else {
expandObjBy(cfg._settings, defCfg);
trim(cfg._settings, defCfg);
expandObjBy(cfg._, defCfg);
trim(cfg._, defCfg);
}
}
/**
A class to manage Objects saved in {@link meta.settings} within property "_settings".
A class to manage Objects saved in {@link meta.settings} within property "_".
Constructor, synchronizes the settings and repairs them if version differs.
@param hash The hash to use for {@link meta.settings}.
@param version The version of the settings, used to determine whether the saved settings may be corrupt.
@@ -71,8 +71,8 @@ Settings.prototype.sync = function (callback) {
var _this = this;
meta.settings.get(this.hash, function (err, settings) {
try {
if (settings._settings) {
settings._settings = JSON.parse(settings._settings);
if (settings._) {
settings._ = JSON.parse(settings._);
}
} catch (_error) {}
_this.cfg = settings;
@@ -87,15 +87,12 @@ Settings.prototype.sync = function (callback) {
@param callback Gets called when done.
*/
Settings.prototype.persist = function (callback) {
var conf = this.cfg._settings,
var conf = this.cfg._,
_this = this;
if (typeof conf === 'object') {
conf = JSON.stringify(conf);
}
meta.settings.set(this.hash, {
_settings: conf,
version: this.cfg.version
}, function () {
meta.settings.set(this.hash, this.createWrapper(this.cfg.v, conf), function () {
if (typeof callback === 'function') {
callback.apply(_this, arguments || []);
}
@@ -103,22 +100,6 @@ Settings.prototype.persist = function (callback) {
return this;
};
/**
Persists the settings if no settings are saved.
@param callback Gets called when done.
*/
Settings.prototype.persistOnEmpty = function (callback) {
var _this = this;
meta.settings.get(this.hash, function (err, settings) {
if (!settings._settings) {
_this.persist(callback);
} else if (typeof callback === 'function') {
callback.call(_this);
}
});
return this;
};
/**
Returns the setting of given key or default value if not set.
@param key The key of the setting to return.
@@ -126,7 +107,7 @@ Settings.prototype.persistOnEmpty = function (callback) {
@returns Object The setting to be used.
*/
Settings.prototype.get = function (key, def) {
var obj = this.cfg._settings,
var obj = this.cfg._,
parts = (key || '').split('.'),
part;
for (var i = 0; i < parts.length; i++) {
@@ -164,8 +145,8 @@ Settings.prototype.getWrapper = function () {
*/
Settings.prototype.createWrapper = function (version, settings) {
return {
version: version,
_settings: settings
v: version,
_: settings
};
};
@@ -184,11 +165,11 @@ Settings.prototype.createDefaultWrapper = function () {
*/
Settings.prototype.set = function (key, val) {
var part, obj, parts;
this.cfg.version = this.version;
this.cfg.v = this.version;
if (val == null || !key) {
this.cfg._settings = val || key;
this.cfg._ = val || key;
} else {
obj = this.cfg._settings;
obj = this.cfg._;
parts = key.split('.');
for (var i = 0, _len = parts.length - 1; i < _len; i++) {
if (part = parts[i]) {
@@ -218,13 +199,13 @@ Settings.prototype.reset = function (callback) {
@param force Whether to update and persist the settings even if the versions ara equal.
*/
Settings.prototype.checkStructure = function (callback, force) {
if (!force && this.cfg.version === this.version) {
if (!force && this.cfg.v === this.version) {
if (typeof callback === 'function') {
callback();
}
} else {
mergeSettings(this.cfg, this.defCfg);
this.cfg.version = this.version;
this.cfg.v = this.version;
this.persist(callback);
}
return this;