diff --git a/packages/xo-server-test-plugin/README.md b/packages/xo-server-test-plugin/README.md new file mode 100644 index 000000000..d71006141 --- /dev/null +++ b/packages/xo-server-test-plugin/README.md @@ -0,0 +1,57 @@ +# xo-server-test-plugin + +## Install + +Either in xo-server's directory: + +``` +> npm i vatesfr/xo-server-test-plugin +``` + +Or globally: + +``` +> npm i -g vatesfr/xo-server-test-plugin +``` + +## Documentation + +### Plugin life cyle + +#### Initialization + +When xo-server starts, it initializes plugins. + +#### Loading plugins + +After initializing the plugins, the xo-server load them. + +#### Test + +XO clients send data to xo-server for testing the configuration and saving it if successful. + +### Principal Methods + +#### The default export + +It is just a factory function which will create an instance of the plugin. Usually it will be called only once, at startup. +Its only parameter is an object which currently only contains the instance of the currently running xo-server. + +#### `configure(configuration) ` + +This method is called each time the plugin is (re-)configured. +Its only parameter is an object which contains the configuration values. + +#### `load() ` + +This method is called to load the plugin. + +#### `unload() ` + +This method is called to unload the plugin. + +#### `test(data) ` + +This method is called if the test option is activated. +Its only parameter is an object which contains the test values. + diff --git a/packages/xo-server-test-plugin/index.js b/packages/xo-server-test-plugin/index.js new file mode 100644 index 000000000..ade9ccf62 --- /dev/null +++ b/packages/xo-server-test-plugin/index.js @@ -0,0 +1,78 @@ +// This is one of the simplest xo-server's plugin than can be created. + +// This (optional) schema is used to describe the expected +// configuration of the plugin. +// +// It will be used to generate a configuration UI (xo-web) and to +// validate the provided configuration. +exports.configurationSchema = { + type: 'object', + properties: { + foo: { + type: 'string' + } + }, + required: ['foo'] +} + +// This (optional) schema is used to test the configuration +// of the plugin. +exports.testSchema = { + type: 'object', + properties: { + test: { + type: 'string' + } + }, + required: ['test'] +} + +// The default export is just a factory function which will create an +// instance of the plugin. +// Usually it will be called only once, at startup. +// +// Its only parameter is an object which currently only contains a +// `xo` property: the instance of the currently running xo-server. +exports.default = function (opts) { + // For simplicity's sake, this plugin returns a plain object, but + // usually it returns a new instance of an existing class. + return { + + // This (optional) method is called each time the plugin is + // (re-)configured. + // + // Note: before being called, the configuration is validated + // against the provided configuration schema. + configure: function (configuration) { + console.log('stub configured', configuration) + }, + + // This method is called to load the plugin. + // + // Note 1: will only be called if the plugin is currently + // unloaded. + // + // Note 2: if the plugin is configurable, will only be called if + // the plugin has been successfully configured. + load: function () { + console.log('stub loaded') + }, + + // This (optional) method is called to unload the plugin. + // + // Note: will only be called if the plugin is currently loaded. + unload: function () { + console.log('stub unloaded') + }, + + // This (optional) method is called to test the configuration of the plugin. + // Note 1: will only be called if the plugin has been successfully configured and is loaded. + // Note 2: before being called, the test configuration is validated + // against the provided test data. + // Note 3: will only be called if the test option is activated. + test: function (data) { + console.log('the configuration is about to be tested') + // TODO: test the configuration, i.e, use the main feature of the plugin and throws any errors. + } + } +} diff --git a/packages/xo-server-test-plugin/package.json b/packages/xo-server-test-plugin/package.json new file mode 100644 index 000000000..70f531bc4 --- /dev/null +++ b/packages/xo-server-test-plugin/package.json @@ -0,0 +1,5 @@ +{ + "private": true, + "name": "xo-server-test-plugin", + "version": "0.0.0" +}