diff --git a/docs/user-guide/context.md b/docs/user-guide/context.md index 66ba337b..467abb60 100644 --- a/docs/user-guide/context.md +++ b/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. -
Note : 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.
+
Note: 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. +
### 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
+`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.
+The second line replaces '123' with '234' in default:count.
+The third line stores '345' in memoryOnly:count.
+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`.
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