Merge remote-tracking branch 'xo-server-test-plugin/master'

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. 
+

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.
+    }
+  }
+}

packages/xo-server-test-plugin/package.json

@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "name": "xo-server-test-plugin",
+  "version": "0.0.0"
+}