changes to docs/user-guide/context.md

docs/user-guide/context.md

@@ -27,46 +27,94 @@ are three context scope levels:
 
 The choice of scope for any particular value will depend on how it is being used.
 
-If a value only needs to be accessed by a single node, such as a Function node, then
-Node context is sufficient.
+If a value only needs to be accessed by a single node, such as a Function node, then Node context is sufficient.
 
-More often context allows some sort of state to be shared between multiple nodes.
-For example, a sensor may publish new values regularly in one flow and you want
-to create a separate HTTP triggered flow to return the most recent value. By
-storing the sensor reading in context it is then available for the HTTP flow to return.
+More often context allows some sort of state to be shared between multiple nodes on the same editor tab. For 
+example, a sensor may publish new values regularly in one flow and you want to create a separate HTTP triggered 
+flow (on the same editor tab) to return the most recent value. By storing the sensor reading as a 'flow' context, 
+it is then available for the HTTP flow to return.
 
-The Global context can be preconfigured with values using the `functionGlobalContext`
-property in the settings file.
+The 'Global' context can be shared across flows on any editor tab, and can be preconfigured with values using 
+the functionGlobalContext property in the settings file.
 
-<div class="doc-callout"><em>Note</em> : for nodes within a subflow, the 'flow' context
-is scoped to the subflow. The nodes cannot access the flow context of the flow
-containing the subflow instance node.</div>
+<div class="doc-callout"><em>Note</em>: for nodes within a subflow, the 'flow' context is scoped to the 
+ subflow. The nodes cannot access the flow context of the flow containing the subflow instance node.
+</div>
 
 
 ### Context stores
 
-By default, context is stored in memory only. This means its contents are cleared
-whenever Node-RED restarts. With the 0.19 release, it is possible to configure
-Node-RED to save context data so it is available across restarts.
+By default, context is stored in memory only. This means its contents are cleared whenever Node-RED 
+restarts. With the 0.19 release, it is possible to configure Node-RED to save context data so it is 
+available across restarts.
 
-The `contextStorage` property in settings.js can be used to configure how context
-data is stored.
+The `contextStorage` property in settings.js can be used to configure how context data is stored.
 
-For example, to enable file-based storage, the following options can be used:
+{% highlight javascript %}
+contextStorage: {
+   storeName: {
+       module: "storeModule"
+   }
+},
+{% endhighlight %}
+
+`storeName`: The storeName used in get/sets<br>
+`storeModule`: Node-RED provides two built-in store modules: `memory` and `localfilesystem`. It is also possible 
+to create custom store plugins. You must specify `localfilesystem` (or your own custom module) to make the data 
+persistent. Full details on the built-in modules, and how to create custom modules, is available on the 
+[api pages](../api/context/).
+
+To enable only file-based (persistant) storage, the following options should be used:
 
 {% highlight javascript %}
 contextStorage: {
    default: {
        module: "localfilesystem"
    }
-}
+},
 {% endhighlight %}
 
-Node-RED provides two built-in store modules: `memory` and `localfilesystem`. It is also
-possible to create custom store plugins.
+To enable file-based and memory storage, the following options could be used:
+
+{% highlight javascript %}
+contextStorage: {
+   memoryOnly : { module: "memory" }
+   default: { module: "localfilesystem" },
+},
+{% endhighlight %}
+
+The first entry will always be used if a 'storeName' is not specifed in a get/set AND none of the 'storeName's 
+are "default". If you try to 'get' or 'set' using a 'storeName' that does not exist, the default will be used 
+and you will see a one time warning in the log.
+
+NOTE: multiple entries in settings.js can lead to confusion. If you have:
 
-Full details on the built-in modules, and how to create custom modules, is
-available on the [api pages](../api/context/).
+{% highlight javascript %}
+contextStorage: {
+  default    : { module: "memory" },
+  storeInFile: { module: "localfilesystem"},
+  memoryOnly : { module: "memory" }
+},
+{% endhighlight %}
+
+and run the following code:
+
+	flow.set("count", 123);               // the value is stored in memory
+	flow.set("count", 234, "default");    // the value is stored in memory
+	flow.set("count", 345, "memoryOnly"); // the value is stored in memory
+
+The first line stores '123' in default:count.<br>
+The second line replaces '123' with '234' in default:count.<br>
+The third line stores '345' in memoryOnly:count.<br>
+If you forget to specify the location in a 'get', you might end up with the wrong value.
+
+SUGGESTION: If you want have all your context data be persistant, setup your settings.js file with the following:
+
+{% highlight javascript %}
+contextStorage: {
+ 	default    : { module: "localfilesystem"}
+},
+{% endhighlight %}
 
 Stores can provide either synchronous or asynchronous access. Synchronous access
 means a call to get data from the store returns immediately with the value. Asynchronous
@@ -80,13 +128,14 @@ existing (pre-0.19) flows can use these stores without any changes.
 
 The easiest way to set a value in context is to use the Change node. For example,
 the following Change node rule will store the value of `msg.payload` in `flow` context
-under the key of `myData`.
+under the key of `myData`. 
 
 <div style="text-align: center"><img src="/docs/user-guide/images/context_change.png" width="488px"></div>
 
 Various nodes can access context directly. For example, the Inject node can be configured
 to inject a context value and the Switch node can route messages based on a value
-stored in context.
+stored in context. If you have more than one `storename` defined, an option will show 
+in the node to pick the one to be used.
 
 ### Using context in a Function node