Add context docs ahead of 0.19

Author: knolleary

_includes/api-toc.html

@@ -28,6 +28,12 @@
             <li {% if page.url contains "/docs/api/storage/methods" %}class="active"{% endif %}><a href="/docs/api/storage/methods">Methods</a>
         </ul>
     </li>
+    <li class="tocheader">
+        <ul>
+            <li class="toctitle{% if page.url == "/docs/api/context/" %} active{% endif %}"><a href="/docs/api/context/">Context Store API</a>
+            <li {% if page.url contains "/docs/api/context/methods" %}class="active"{% endif %}><a href="/docs/api/context/methods">Methods</a>
+        </ul>
+    </li>
     <li class="tocheader">
         <ul>
             <li class="toctitle{% if page.url == "/docs/api/ui/" %} active{% endif %}"><a href="/docs/api/ui/">Editor Widgets</a>

_includes/user-guide-toc.html

@@ -8,6 +8,7 @@
             <li {% if page.url == "/docs/user-guide/nodes" %}class="active"{% endif %}><a href="/docs/user-guide/nodes">The core nodes</a></li>
             <li {% if page.url == "/docs/writing-functions" %}class="active"{% endif %}><a href="/docs/writing-functions">Writing Functions</a></li>
             <li {% if page.url == "/docs/user-guide/messages" %}class="active"{% endif %}><a href="/docs/user-guide/messages">Working with messages</a></li>
+            <li {% if page.url == "/docs/user-guide/context" %}class="active"{% endif %}><a href="/docs/user-guide/context">Working with context</a></li>
         </ul>
     </li>
     <li class="tocheader">

docs/api/context/index.md

@@ -0,0 +1,79 @@
+---
+layout: docs
+toc: api-toc.html
+title: Context Store API
+---
+
+**New in 0.19**
+
+The Context Store API provides a pluggable way to configure where context data is
+stored.
+
+By default, Node-RED uses a memory-based implementation of this API. It also provides
+a file-based implementation.
+
+The API functions are documented [here](methods/).
+
+### Configuration
+
+The `contextStorage` property in settings.js can be used to configure context storage.
+
+It is an object with one or more named context store configurations.
+
+{% highlight javascript %}
+contextStorage: {
+   default: {
+       module:"memory",
+       config: {
+           customOption: 'value'
+       }
+   }
+}
+{% endhighlight %}
+
+Each context store configuration consists of two parts; a `module` property and a `config`
+property.
+
+The `module` property identifies the context store plugin to use. It can either be
+the name of built-in module (currently either `memory` or `file`), or it should be
+a module that has been loaded using `require`.
+
+{% highlight javascript %}
+contextStorage: {
+   default: {
+       module:"memory",
+   },
+   custom: {
+       module:require("my-custom-store")
+   }
+}
+{% endhighlight %}
+
+The `config` property is an object that is passed to the module to provide an
+custom options.
+
+### Store Module API
+
+A custom plugin's module must export a single constructor function. This function is called when a
+new instance of the plugin is required. The function is passed the value of the `config`
+property for the given instance. This allows the runtime to have multiple instances
+of the same store plugin, each with its own configuration.
+
+{% highlight javascript %}
+
+var ContextStore = function(config) {
+    this.config = config;
+}
+
+ContextStore.prototype.open = function() { ... }
+
+
+module.exports = function(config){
+    return new ContextStore(config);
+};
+
+{% endhighlight %}
+
+
+The object returned by the constructor function must implement all of the functions
+detailed [here](methods/).

docs/api/context/methods/index.md

@@ -0,0 +1,131 @@
+---
+layout: docs
+toc: api-toc.html
+title: Context Store API
+---
+
+**New in 0.19**
+
+A Context Storage plugin is a node.js module that exposes a function on its `module.exports`
+that can be used to create new instances of the plugin. The object returned by the
+function must have the following functions:
+
+ Function                                                      | Description
+---------------------------------------------------------------|-------------------------
+[ContextStore.open()](#contextstoreopen)                       | Open the storage ready for use
+[ContextStore.close()](#contextstoreclose)                     | Close the storage
+[ContextStore.get(scope, key, callback)](#contextstoregetscope-key-callback) | Get values from the store
+[ContextStore.set(scope, key, value, callback)](#contextstoresetscope-key-value-callback) | Set values in the store
+[ContextStore.keys(scope, calback)](#contextstorekeysscope-callback) | Get a list of all keys in the store
+[ContextStore.delete(scope)](#contextstoredeletescope)               | Delete all keys for a given scope
+[ContextStore.clean(activeNodes)](#contextstorecleanactivenodes)     | Clean the context store
+
+### ContextStore.open()
+
+Open the storage ready for use. This is called before any store values are accessed.
+
+Returns a `Promise` that resolves when the store is ready for access.
+
+### ContextStore.close()
+
+Called when the runtime is stopped so no further key values will be accessed.
+
+Returns a `Promise` that resolves with the store is closed.
+
+### ContextStore.get(scope, key, [callback])
+
+Argument | Description
+---------|------------------------------
+scope    | the scope of the key
+key      | the key, or array of keys, to return the value(s) for.
+callback | *optional* a callback function to invoke with the key value
+
+The `key` argument can be either a String identifying a single key, or an Array
+of Strings identifying multiple keys to return the values for.
+
+
+If the optional `callback` argument is provided, it must be a function that takes
+two or more arguments:
+
+```
+function callback(error, value1, value2, ... ) {
+
+}
+```
+
+If no callback is provided, and the store supports synchronous access, the
+`get` function should return the individual value, or array of values for the keys.
+If the store does not support synchronous access it should throw an error.
+
+### ContextStore.set(scope, key, value, [callback])
+
+Argument | Description
+---------|------------------------------
+scope    | the scope of the key
+key      | the key, or array of keys, to set the value(s) for.
+value    | the value, or array of values
+callback | *optional* a callback function to invoke when the value is set
+
+The `key` argument can be either a String identifying a single key, or an Array
+of Strings identifying multiple keys to set.
+
+`key`        | `value`        | Action
+-------------|----------------|----------------
+String       | Any            | Stores `value` under `key`
+Array        | Array          | Stores each element of the `value` array under the corresponding `key` value. If `value` has fewer elements than `key`, it sets the missing values to `null`.
+Array        | not-Array      | Stores `value` as the value of the first key - uses `null` for any remaining keys.
+
+
+If the optional `callback` argument is provided, it will be called when the value
+has been stored. It takes a single argument, `error`, to indicate any errors hit
+whilst storing the values.
+
+```
+function callback(error) {
+
+}
+```
+
+If no callback is provided, and the store supports synchronous access, the
+`set` function should return once the value is stored. If the store does not support
+synchronous access it should throw an error.
+
+### ContextStore.keys(scope, [callback])
+
+Argument    | Description
+------------|------------------------
+scope       | the scope of the keys to return
+callback    | *optional* a callback function to invoke with the list of keys
+
+Gets a list of all keys under the given scope.
+
+If the optional `callback` argument is provided, it must be a function that takes
+two or more arguments:
+
+```
+function callback(error, keys) {
+
+}
+```
+
+If no callback is provided, and the store supports synchronous access, the
+`keys` function should return the array of keys. If the store does not support
+synchronous access it should throw an error.
+
+
+### ContextStore.delete(scope)
+
+Argument    | Description
+------------|------------------------
+scope       | the scope to delete
+
+
+### ContextStore.clean(activeNodes)
+
+Argument    | Description
+------------|------------------------
+activeNodes | a list of all node/flow ids that are still active
+
+Returns a promise that resolves when store has removed any context scopes that
+are no longer required. The `activeNodes` list can be used to identify what nodes
+and flows are still considered active.

docs/api/index.md

@@ -18,6 +18,10 @@ This API can be used when embedding Node-RED into another application.
 This API provides a pluggable way to configure where the Node-RED runtime stores
 data.
 
+### [Context Store API](context)
+
+**New in 0.19** : This API provides a pluggable way to store context data outside of the runtime.
+
 ### [Editor UI Widgets](ui)
 
 A set of jQuery widgets that can be used within a node's edit template. _Since 0.14_

docs/configuration.md

@@ -18,7 +18,7 @@ user-provided settings file. It can also be used as a starting point for creatin
 your own settings file. It can be seen on GitHub [here](https://github.com/node-red/node-red/blob/master/settings.js).
 
 <div class="doc-callout">
-<em>Note</em>:  The <code>settings.js</code> file exports a <em>JavaScript object</em>.  To configure Node-RED you should understand how to modify a JavaScript object by adding new or modifying existing key/value pairs.
+<em>Note</em> :  The <code>settings.js</code> file exports a <em>JavaScript object</em>.  To configure Node-RED you should understand how to modify a JavaScript object by adding new or modifying existing key/value pairs.
 </div>
 
 When [embedded](embedding), they are passed in the call to `RED.init()`.
@@ -197,7 +197,7 @@ functionGlobalContext
 
       var myos = global.get('osModule');
 
- <div class="doc-callout"><em>Note</em>: Prior to Node-RED v0.13, the documented
+ <div class="doc-callout"><em>Note</em> : Prior to Node-RED v0.13, the documented
  way to use global context was to access it as a sub-property of <code>context</code>:
  <pre>context.global.foo = "bar";
  var osModule = context.global.osModule;</pre>

docs/creating-nodes/context.md

@@ -4,40 +4,28 @@ toc: creating-nodes-toc.html
 title: Node context
 ---
 
-A node can store data within its context object. This context object is reset
-whenever the node is redeployed and when Node-RED is restarted.
+A node can store data within its context object.
 
-{% highlight javascript %}
-// Access the node's context object
-var context = this.context();
-
-var count = context.get('count') || 0;
-count += 1;
-context.set('count',count);
+For more information about context, read the [Working with Context guide](../user-guide/context).
 
-{% endhighlight %}
+There are three scopes of context available to a node:
 
-##### Flow context
+- Node - only visible to the node that set the value
+- Flow - visible to all nodes on the same flow (or tab in the editor)
+- Global - visible to all nodes
 
-The flow-level context is shared by all nodes on a given tab.
+Unlike the Function node which provides predefined variables to
+access each of these contexts, a custom node must access these
+contexts for itself:
 
 {% highlight javascript %}
-var flowContext = this.context().flow;
-var count = flowContext.get('count')||0;
-{% endhighlight %}
-
-##### Global context
+// Access the node's context object
+var nodeContext = this.context();
 
-The global context is shared by, and accessible to all nodes. For example to
-make the variable `foo` available globally:
+var flowContext = this.context().flow;
 
-{% highlight javascript %}
 var globalContext = this.context().global;
-globalContext.set("foo","bar");  // this is now available to other nodes
 {% endhighlight %}
 
-##### Accessing context in a Function node
-
-In the Function node, the `flow` and `global` context objects are made available
-as top-level objects. See [this section](/docs/writing-functions#storing-data)
-for more information.
+Each of these context objects has the same `get`/`set` functions described
+in the [Writing Functions guide](/docs/writing-functions#storing-data).

docs/creating-nodes/first-node.md

@@ -179,7 +179,7 @@ On Windows with older versions of npm, use `mklink` instead:
     mklink /D node_modules\node-red-contrib-example-lower-case C:\Users\my_name\Documents\GitHub\node-red-contrib-example-lower-case
 
 <div class="doc-callout">
-<em>Note</em>:  npm 5 will add your module as a dependency in the <code>package.json</code> file located in your user directory.  If you want to prevent this, use the npm <code>--no-save</code> option.
+<em>Note</em> :  npm 5 will add your module as a dependency in the <code>package.json</code> file located in your user directory.  If you want to prevent this, use the npm <code>--no-save</code> option.
 </div>
 
 ### Unit Testing

docs/creating-nodes/packaging.md

@@ -50,7 +50,7 @@ To help make the nodes discoverable within the npm repository, the file should
 include `node-red` in its `keywords` property. This will ensure the package
 appears when [searching by keyword](https://www.npmjs.org/browse/keyword/node-red).
 
-<div class="doc-callout"><em>Note</em>: Please do NOT add the `node-red` keyword until
+<div class="doc-callout"><em>Note</em> : Please do NOT add the `node-red` keyword until
 you are happy that the node is stable and working correctly, and documented sufficiently
 for others to be able to use it.</div>
 

docs/getting-started/installation.md

@@ -64,7 +64,7 @@ Once cloned, the core pre-requisite modules must be installed :
     npm install
 
 <div class="doc-callout">
-<em>Note</em>: when running from a clone of the git repository, it is necessary
+<em>Note</em> : when running from a clone of the git repository, it is necessary
 to install all dependencies, not just the production level ones. This is why the
  <code>--production</code> option should not be used.
 </div>