add latest docu of blockly features of M2 (#2297)

* add latest docu of blockly features of M2

Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>

---------

Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>
Co-authored-by: Florian Hotze <florianh_dev@icloud.com>

configuration/blockly/index.md

@@ -165,6 +165,47 @@ Three YouTube tutorials have been made available via the [openHAB YouTube channe
 
 Also view ![youtube](../images/blockly/youtube-logo-small.png) [Overview of the Blockly Sections](https://youtu.be/EdllUlJ7p6k?t=558)
 
+### Using Variables
+
+For a long time Blockly only provided untyped variables.
+Even though this seems to be more straight forward and provides the flexibility to put any type into that variable, it creates some challenges to openHAB Blockly to generate the right code.
+
+All blocks in Blockly have input and output types defined which allows the editor to check whether one particular block can be used as input for a different block.
+This becomes challenging with the standard untyped variables because the type of these is basically none which means that the Blockly editor is not able to check whether this block is allowed or not.
+This requires Blockly to make a default guess on the variable's type, which often is the wrong type guess and therefore causes wrong code to be generated - your rule will not work.
+
+Therefore, a new variable section was introduced:
+
+![typed variables](../images/blockly/blockly_typed_variables1.png)
+
+**In general, always prefer Typed Variables over normal Variables!**
+
+In the very seldom case where you may mix types or you want to use a type that is not provided in the dialog, only then choose non-typed variables.
+
+Create a typed variable by clicking on the following button:
+
+![create typed variable](../images/blockly/blockly_typed_variables2.png)
+
+This will open up the following dialog:
+
+![create typed variable dialog](../images/blockly/blockly_typed_variables3.png)
+
+Hint: Always choose the type of the variable first because it is not possible to change the type afterwards!
+
+- Enter the name of the variable: it is recommended to use a concatenation of the variable name plus the type like _powerItemName_ as it is hard to know later on what type the variable has.
+- Don't forget to select the right type (here "Item name") before clicking ok because it cannot be changed later.
+- Click ok to create the variable
+
+You will notice that this typed variable can only be used in inputs where normally an Item (name) block would have been allowed.
+
+Here are some examples how these typed variable can or even should be used:
+
+![blockly_typed_variables_examples.png](../images/blockly/blockly_typed_variables_examples.png)
+
+- In the above example the variable name postfix _Var_ was sometimes used which is more like a personal taste and isn't necessary.
+- Blockly loops can also take typed variables, and it is especially useful in these cases to make sure the type that is returned by the list (e.g. "get members of group") matches the type of the variable because it allows blocks that use the list items (e.g. "get state of item") to behave correctly.
+- As it can be seen in the loop example it is very helpful if the variable name contains the type.
+
 ### Items and Things
 
 _Items_ and _Things_ are the [major entities of openHAB](https://www.openhab.org/docs/concepts/) to control and monitor the home.
@@ -249,6 +290,15 @@ These blocks enable storing information _for a rule_ that is kept after the rule
 
 See [Value Storage](rules-blockly-value-storage.html) section.
 
+### HTTP
+
+These blocks allow sending HTTP requests and receiving the response.
+
+[![HTTP](../images/blockly/blockly-http-overview-small.png "HTTP")
+](rules-blockly-http.html)
+
+See [HTTP](rules-blockly-http.html) section.
+
 ### Run & Process (Rules, Scripts and Transformations)
 
 This section allows calling rules or other scripts, retrieving attributes provided by the rule context or transforming values via different conversion methods (e.g. map, regex, jsonpath)

configuration/blockly/rules-blockly-http.md

@@ -0,0 +1,78 @@
+---
+layout: documentation
+title: Rules Blockly - Logging
+---
+<!-- markdownlint-disable MD036 -->
+
+# HTTP
+
+[return to Blockly Reference](index.html#http)
+
+## Introduction
+
+This section explains the blocks that allow sending HTTP requests.
+
+## HTTP Requests
+
+There is one block that handles all type of requests.
+Depending on the required functionality it changes its design.
+
+![http-overview](../images/blockly/blockly-http-overview.png)
+
+### Option Toggles
+
+There are two toggle buttons that allow the block to be small for simple requests and add further options to be used:
+
+![http-toggle](../images/blockly/blockly-http-toggles.png)
+
+- Clock: enables the timeout option
+- H: enables the header option and allows to provide headers during the request via a [Dictionary](rules-blockly-standard-ext.md#dictionary-for-managing-key--value-pairs)
+
+### HTTP Request GET
+
+_Function:_ Send an HTTP GET request to a server and receive the response
+
+The simplest form is shown by default and accepts the destination URI as String.
+
+![http-get-simple](../images/blockly/blockly-http-get-simple.png)
+
+By activating the toggles the timeout and request headers can be provided.
+See the [POST-Request](#http-request-post) below for an example showing these additional fields.
+
+### HTTP Request POST
+
+_Function:_ Send an HTTP POST request to a server and receive the response
+
+The simplest form is shown by default and accepts the destination URI as String and in comparison to the [GET-Request](#http-request-get) adds a section for the payload which takes two parameters:
+
+- the MIME-type of the content to be sent
+- the content to be sent to the destination
+
+![http-post-simple](../images/blockly/blockly-http-post-simple.png)
+
+Here is a more complex example that additionally sets a header and the timeout:
+
+![http-post-complex](../images/blockly/blockly-http-post-complex.png)
+
+### HTTP Request PUT
+
+_Function:_ Send an HTTP PUT request to a server and receive the response
+
+The simplest form is shown by default and accepts the destination URI as String and is similar in functionality to the [POST-Request](#http-request-post):
+
+- the MIME-type of the content to be sent
+- the content to be sent to the destination
+
+![http-put-simple](../images/blockly/blockly-http-put-simple.png)
+
+### HTTP Request DELETE
+
+_Function:_ Send an HTTP DELETE request to a server and receive the response
+
+The simplest form is shown by default and accepts the destination URI as String.
+
+![http-delete-simple](../images/blockly/blockly-http-delete-simple.png)
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#http)

configuration/blockly/rules-blockly-items-things.md

@@ -100,6 +100,8 @@ Function: Gets the members of a **group**
 - returns a collection of items which should be used with a for-each-block to loop over the items
 - it can be attached to a log-block which would list all items in that block in the form a string representation as follows
 
+**Hint**: Make sure you are using [typed variables](./index.html#using-variables)!
+
 ```json
 GF_IndirectLights (Type=GroupItem, BaseType=SwitchItem, Members=9, State=OFF, Label=Indirekten Lichter, Category=light, Tags=[Lightbulb], Groups=[Lights]),LichterOG (Type=GroupItem, BaseType=SwitchItem, Members=4, State=ON, Label=Lichter OG, Category=light, Groups=[Lights]),LichterEG (Type=GroupItem, BaseType=SwitchItem, Members=5, State=ON, Label=Lichter EG, Category=light, Groups=[Lights])
 ```
@@ -120,13 +122,15 @@ Function: Gets all items with the given tags which you can iterate over via a lo
 - multiple tags can be provided which then need to be separated with a comma
 - if multiple tags are given, the item must have all of the tags ("and"-condition)
 
+**Hint**: Make sure you are using [typed variables](./index.html#using-variables)!
+
 :::tip
 
 If you need an item that has one of multiple tags, then you need to use one block of each and then use the ["concatenate list block"](https://www.openhab.org/docs/configuration/blockly/rules-blockly-standard-ext.html#concatenate-list) to combine the results.
 
 :::
 
-### Get particular attributes of an item
+### Get particular attributes of an Item
 
 ![blockly-getItemAttributes](../images/blockly/blockly-getItemAttributes.png)
 
@@ -167,11 +171,10 @@ Since openHAB 4.1 an optimization was introduced that simplifies the usage:
 It allows to attach the item block directly instead of having to use the intermediate getItem-Block.
 Internally Blockly detects the added type and applies the right code generation.
 
-_Strict block type usage when using Variables_
+_Use typed variables:_
 
-Due to the fact that Blockly is not able to detect the type of the value that has been assigned to a variable, there is no reliable way to allow that input flexibility for variables.
-Therefore, when using variables the set variable to block must be used together with the get item block and must not be used together with the item block.
-See the above examples for right and wrong usage.
+Due to the fact that Blockly provides untyped variables it is then not able to detect the type of the value that has been assigned to a variable which may result into unexpected behaviour.
+Therefore, always use a [typed variable](./index.html#using-variables) instead
 
 **Special handling for Arrays**
 
@@ -183,6 +186,8 @@ Therefore
 
 ![blockly-specialArrayHandling](../images/blockly/blockly-specialArrayHandling.png)
 
+- See more infos in the section about [typed variables](./index.html#using-variables)!
+
 ### Send Command
 
 ![blockly-sendCommand](../images/blockly/blockly-sendCommand.png)
@@ -274,6 +279,7 @@ Using variables and loops properties like field1, field2, field3 can even be acc
 
 Function: Retrieves a specific **Thing** for use in other thing related functions.
 
+- To be specific this only provides a thing picker that provides the ID of that thing (and not the thing object itself that holds several properties)
 - Clicking 'MyThing' displays a list of **Things** to pick from
 - Technically this block returns the thingUid of the thing as a String
 - Learn more about [things](https://www.openhab.org/docs/configuration/things.html) or [thing-concepts](https://www.openhab.org/docs/concepts/things.html)
@@ -282,16 +288,25 @@ Function: Retrieves a specific **Thing** for use in other thing related function
 
 ![blockly-thingExample](../images/blockly/blockly-thingExample.png)
 
-will write the following into the log
+will write the following ID of the thing into the log
 
 ```text
 thing name = nanoleaf:controller:645E3A484A83
 ```
 
+### Get Thing
+
+![blockly-thing](../images/blockly/blockly-thing-object.png)
+
+Function: Gets a **Thing** for use in other thing related functions
+
+- Clicking 'MyThing' displays a list of **Things** to pick from.
+- Technically this block returns a thing _object_, to be used to retrieve specific attributes using other blocks (see below).
+
 ### Get Thing Status
 
 ![blockly-getThingStatus](../images/blockly/blockly-getThingStatus.png)
-Function: Gets a **Thing Status** for use in other Thing related functions
+Function: Gets the **Thing Status**
 
 - Clicking 'MyThing' displays a list of **Things** to pick from.
 - Technically this block returns a [ThingStatus](https://www.openhab.org/docs/concepts/things.html#thing-status) - a String with one of the following statuses
@@ -303,6 +318,35 @@ Function: Gets a **Thing Status** for use in other Thing related functions
  - REMOVING
  - REMOVED
 
+### Get particular attributes of a Thing
+
+![blockly-getThingAttributes](../images/blockly/blockly-getThingAttributes.png)
+
+Function: Get particular attributes of a Thing
+
+It requires a [thing object](#get-thing) to be connected.
+
+These attributes are returned with the following types:
+
+- UID (unique Thing ID): String
+- label: String
+- status (like ONLINE/OFFLINE): String
+- status info (status plus further info like "light not reachable"): String
+- location: String
+- thing type UID (unique ID of the Thing type): String
+- bridge UID (unique ID of the Bridge): String
+
+### Get Things
+
+Function: Gets all things and returns a list of [Thing-Objects](#get-thing).
+
+![blockly-getThings](../images/blockly/blockly-get-things.png)
+
+The following loop iterates over all things and logs out the status.
+Note that it uses a [typed variable](./index.html#using-variables) for that.
+
+![blockly-thingsLoop](../images/blockly/blockly-things-loop.png)
+
 ## Return to Blockly Reference
 
 [return to Blockly Reference](index.html#items-and-things)

configuration/blockly/rules-blockly-logging.md

@@ -10,7 +10,7 @@ title: Rules Blockly - Logging
 
 ## Introduction
 
-This section explains only the blocks that have been added to the standard blocks by openHAB
+This section explains the blocks that have been added to allow logging.
 
 [[toc]]
 

configuration/blockly/rules-blockly-persistence.md

@@ -26,7 +26,7 @@ The date-blocks shown in this section are described previously in [Date handling
 Persistence blocks enable access of historical data stored by the default persistence service.
 For more information on persistence, the default service, and its configuration see the [persistence documentation](https://www.openhab.org/docs/configuration/persistence.html).
 
-The date-blocks shown in this section are described previously in [Date handling blocks](https://community.openhab.org/t/blockly-reference/128785#date-handling-blocks-31).
+The date-blocks shown in this section are described in [Date handling blocks](https://community.openhab.org/t/blockly-reference/128785#date-handling-blocks-31).
 
 More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Using Persistence data](https://youtu.be/KwhYKy1_qVk?t=1440)
 
@@ -36,6 +36,19 @@ More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo
 
 _Function:_ computes any of the below functions for the given item since the time provided by _ZonedDateTime_-Block
 
+openHAB supports history and future values.
+A typical example for future values is a weather forecast.
+Due to adding future values in openHAB the amount of attributes has been vastly increased and the names had to be renamed to become more specific in terms of historic and future states.
+
+**Important:** **Due to a breaking change of the internal methods in openHAB 4.2, Blockly rules that use persistence methods need to be migrated once.**
+This does not happen automatically but needs to be done opening the blockly rule once and re-save it.
+Blockly then automatically rewrites the rule to be compatible.
+
+Values:
+
+The following values are available as _historic_ and _future_ representations.
+
+- persisted state: gets the persisted state at a certain point in time
 - average: gets the average value of the State of a persisted Item since a certain point in time.
 This method uses a time-weighted average calculation
 - delta: gets the difference in value of the State of a given Item since a certain point in time
@@ -45,15 +58,16 @@ This method uses a time-weighted average calculation
 - minimum: gets the minimum value of the State of the given Item since a certain point in time
 - maximum: gets the maximum value of the State of the given Item since a certain point in time
 - sum: gets the sum of the State of the given Item since a certain point in time
-- historic state: gets the historic state at a certain point in time
 
 In the case of the following two functions the block changes its appearance by replacing the time with an option to chose if the equal value should be skipped or not:
 
 ![previous-block](../images/blockly/blockly-persistence-get-previous.png)
 
 - previous state value: Gets the previous state with option to skip to different value as current
+- next state value: Gets the next state with option to skip to different value as current
 - previous state numeric value: same as above but directly returns a number without a unit
 - previous state value time: Gets the time when previous state last occurred with option to skip to different value as current
+- next state value time: Gets the time for which the next state is available with option to skip to different value as current
 
 The persistence dropdown allows to select the persistence storage from which the value should be retrieved.
 It automatically shows only the storage types that are currently installed on your openHAB instance.

configuration/blockly/rules-blockly-standard-ext.md

@@ -12,13 +12,17 @@ title: Rules Blockly - openHAB Extensions to the Standard
 
 This section explains only the blocks that have been added to the standard blocks by openHAB
 
-[[toc]]
-
 ## Logic
 
 One of the most commonly used standard blocks are conditions blocks.
 More about conditions can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [How to use IF and ELSE](https://youtu.be/hSRfooBKn9A?t=445).
 
+A specific block that was added by openHAB is the **UNDEFINED**-Block which allows better comparison of undefined values.
+
+Here is an example on how to use it:
+
+![quantity-math-operations](../images/blockly/blockly-logic-undefined.png)
+
 ## Math
 
 The Math section mainly consists of standard Blockly blocks.
@@ -239,7 +243,7 @@ Example:
 ## Loops
 
 Even though there a no specialized openHAB blocks provided, loops are used rather often.
-Therefore there is a good introduction to loops available which can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Loops in Blockly](https://youtu.be/EdllUlJ7p6k?t=1947)
+Therefore, there is a good introduction to loops available which can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Loops in Blockly](https://youtu.be/EdllUlJ7p6k?t=1947).
 
 ## Functions
 

configuration/blockly/rules-blockly-timers-and-delays.md

@@ -37,6 +37,34 @@ and cancels the same timer in Rule 2
 
 ![timer-shared-cancel](../images/blockly/blockly-timer-shared-cancel.png)
 
+## Timer context
+
+Timers provide a statement block where the blocks reside that are run when the timer triggers.
+The context allows data to be provided which is later used when the blocks are triggered by the timer (note that in many cases you can just leave the context empty or provide an [undefined block](rules-blockly-standard-ext.md#logic)).
+
+To provide a context put any block to the context input, which can be a block of any type like String, Number, a variable or even a Dictionary which could hold several values via a key/value mapping.
+
+The context can be used within the timer statement block by utilizing the "timer context" block:
+
+![blockly-timer-context.png](../images/blockly/blockly-timer-context.png)
+
+Here are some examples how this feature can be used:
+
+![timer-context-examples](../images/blockly/blockly-timer-context-examples.png)
+
+The loop is in particular interesting to look at:
+
+- The loop counts from 1 to 10 (actually to 9).
+- It therefore creates 5 timers where the first is triggered after 1 seconds, the second after 3 seconds and so on.
+- Each timer's name is based on that counter index, i.e. the first timer's name is LoopCreatedTimer1 and the last timer is named LoopCreatedTimer9.
+- The timer name is then provided to the timer block itself via the context which could then be used in various ways (here it just prints it out).
+
+In case you don't like the context input part be empty you can add the undefined- or null-block that can be found in the [logic section](rules-blockly-standard-ext.md#logic) to the timer:
+
+![timer-context-undefined](../images/blockly/blockly-timer-context-undefined.png)
+
+## Timer Blocks
+
 ### Wait for
 
 ![waitfor](../images/blockly/blockly-waitfor.png)