From 2cb173bba6c6d53b2cd8410546780861280d4304 Mon Sep 17 00:00:00 2001 From: juggledad Date: Thu, 18 Oct 2018 06:10:41 -0400 Subject: [PATCH 1/4] expanded the explainations about context and added some examples. --- docs/user-guide/context.md | 97 ++++++++++++++++++++++++++++---------- 1 file changed, 73 insertions(+), 24 deletions(-) diff --git a/docs/user-guide/context.md b/docs/user-guide/context.md index 66ba337b..ac74564a 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 %} + +To enable file-based and memory storage, the following options could be used: + +{% highlight javascript %} +contextStorage: { + memoryOnly : { module: "memory" } + default: { module: "localfilesystem" }, +}, {% endhighlight %} -Node-RED provides two built-in store modules: `memory` and `localfilesystem`. It is also -possible to create custom store plugins. +The first entry will always be used when you don't specify it in a get/set `if` none of the `storeName`s +are "default". If you try to 'get' or 'set' using a `storeName` that does not exist it will use the default +and you will see a one time warning in the log. -Full details on the built-in modules, and how to create custom modules, is -available on the [api pages](../api/context/). +NOTE: multiple entries in settings.js can lead to confusion. If you have: + +{% 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 a file + +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 From 8de0f3f276d93e9e90ade3afbdda49e1b23e9dfe Mon Sep 17 00:00:00 2001 From: juggledad Date: Thu, 18 Oct 2018 06:24:38 -0400 Subject: [PATCH 2/4] minor spelling and reformatind changes --- docs/user-guide/context.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/user-guide/context.md b/docs/user-guide/context.md index ac74564a..bc337b8c 100644 --- a/docs/user-guide/context.md +++ b/docs/user-guide/context.md @@ -30,15 +30,16 @@ 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. 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 +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 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 @@ -57,7 +58,7 @@ contextStorage: { }, {% endhighlight %} -`storeName`: The storeName used in get/sets +`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 @@ -82,8 +83,8 @@ contextStorage: { }, {% endhighlight %} -The first entry will always be used when you don't specify it in a get/set `if` none of the `storeName`s -are "default". If you try to 'get' or 'set' using a `storeName` that does not exist it will use the default +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: @@ -102,10 +103,9 @@ and run the following code: flow.set("count", 234, "default"); // the value is stored in memory flow.set("count", 345, "memoryOnly"); // the value is stored in a file -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 - +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: From 6a5909636d6e621c5c9212678b822b9d95652e51 Mon Sep 17 00:00:00 2001 From: juggledad Date: Fri, 19 Oct 2018 07:49:01 -0400 Subject: [PATCH 3/4] Fixed incorrect comment and added some line breaks --- docs/user-guide/context.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/user-guide/context.md b/docs/user-guide/context.md index bc337b8c..c6566522 100644 --- a/docs/user-guide/context.md +++ b/docs/user-guide/context.md @@ -78,7 +78,7 @@ To enable file-based and memory storage, the following options could be used: {% highlight javascript %} contextStorage: { - memoryOnly : { module: "memory" } + memoryOnly : { module: "memory" } default: { module: "localfilesystem" }, }, {% endhighlight %} @@ -92,8 +92,8 @@ NOTE: multiple entries in settings.js can lead to confusion. If you have: {% highlight javascript %} contextStorage: default : { module: "memory" }, - storeInFile: { module: "localfilesystem"}, - memoryOnly : { module: "memory" } + storeInFile: { module: "localfilesystem"}, + memoryOnly : { module: "memory" } }, {% endhighlight %} @@ -101,11 +101,11 @@ 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 a file + 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. +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: From 0695c5f599af4b60ac9edbec4e4863755efe46ce Mon Sep 17 00:00:00 2001 From: juggledad Date: Fri, 19 Oct 2018 17:53:48 -0400 Subject: [PATCH 4/4] Fixed a couple missing '{' in the examples --- docs/user-guide/context.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/context.md b/docs/user-guide/context.md index c6566522..467abb60 100644 --- a/docs/user-guide/context.md +++ b/docs/user-guide/context.md @@ -90,7 +90,7 @@ and you will see a one time warning in the log. NOTE: multiple entries in settings.js can lead to confusion. If you have: {% highlight javascript %} -contextStorage: +contextStorage: { default : { module: "memory" }, storeInFile: { module: "localfilesystem"}, memoryOnly : { module: "memory" } @@ -111,7 +111,7 @@ If you forget to specify the location in a 'get', you might end up with the wron SUGGESTION: If you want have all your context data be persistant, setup your settings.js file with the following: {% highlight javascript %} -contextStorage: +contextStorage: { default : { module: "localfilesystem"} }, {% endhighlight %}