Blockly updates m3 (#2087)

* fix some typos in Readme

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

* add blockly docu for latest improvements

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

---------

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

configuration/blockly/rules-blockly-date-handling.md

@@ -224,11 +224,14 @@ More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo
 
 ### Get String representation of date ("text of")
 
+![get-date-string](../images/blockly/blockly-get-date-string-without.png)
+
 ![date-tostring](../images/blockly/blockly-get-date-string.png)
 
 Type: _String_
 
-Returns the String representation of a given _ZonedDateTime_-block, with or without the time.
+Returns the String representation of a given _ZonedDateTime_-block, with, without the time or formatted in openHAB time (like in the logs).
+It also allows to return the date in a custom format which can be provided in a separate block.
 
 since 3.3: also returns the same datetime format that is used by openHAB itself
 

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

@@ -139,8 +139,10 @@ These attributes are returned with the following types:
 - name: String
 - label: String
 - state: State
+- numeric state: Number
+- quantity state: [Quantity](rules-blockly-uom.html#unit-of-measurement-blocks)
 - category: String
-- tag: Array, e.g.
+- tags: Array, e.g.
 
 ```json
 [plannedTimes]

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

@@ -43,6 +43,12 @@ _Function:_ The bitwise NOT (~) operator inverts the bits of its operand.
 
 ![blockly-bitwise-not.png](../images/blockly/blockly-bitwise-not.png)
 
+### Rounding
+
+The standard block has been extended to provide a rounding function with the ability to set the number of decimal places:
+
+![math-round](../images/blockly/blockly-math-round.png)
+
 ## Text
 
 The Text section is the general section that allows text or string manipulation
@@ -143,6 +149,8 @@ Example
 ![lists-overview](../images/blockly/blockly-lists-dictionary-overview.png)
 ![lists-overview-concat](../images/blockly/blockly-lists-concatenate.png)
 
+![blockly-map-for-each](../images/blockly/blockly-map-for-each.png)
+
 ### Dictionary for managing key / value pairs
 
 The dictionary is a holder for key value pairs that can be passed along as one.
@@ -167,6 +175,18 @@ _Function:_ Retrieves the value of the key in the given directory
 
 ![dictionary-getkey-example](../images/blockly/blockly-lists-dictionary-getkey-example.png)
 
+### Loop over a dictionary
+
+This block can be found in the Loops section and is a dedicated block that allows to iterate over the elements of a dictionary.
+The loop provides the value into the variable that was choosen in the drop down.
+See the examples below how the loop can be used.
+
+![map-for-each](../images/blockly/blockly-map-for-each.png)
+
+Either the dictionary itself can be provided directly or via a variable.
+
+![dictionary-foreach-example](../images/blockly/blockly-map-foreach-example.png)
+
 ### Concatenate lists
 
 ![lists-overview-concat](../images/blockly/blockly-lists-concatenate.png)

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

@@ -18,13 +18,24 @@ More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo
 
 ## Overview of the Timers and Delays category
 
-> ![timers-and-delays](../images/blockly/blockly-timers-and-delays-1.png) ![timers-and-delays.png](../images/blockly/blockly-timers-and-delays-2.png)
+![timers-and-delays](../images/blockly/blockly-timers-overview.png)
 
-## Timer Naming
+## Timer Naming and Scope
 
 Timers are created and referred to by name, enabling manipulation within a rule.
 
-> **Important**: a named timer is _only_ available within the same rule. The same timer _cannot_ be accessed via a different rule. A different rule with a timer of the same name results into two separate timers.
+A timer is by default created within the scope of that particular rule which is called  a "private" timer.
+When the timer is created as a shared timer it can also be accessed under this name from a different rule.
+
+![timer-scope](../images/blockly/blockly-timer-shared.png)
+
+This example starts a timer in Rule 1
+
+![timer-shared](../images/blockly/blockly-timer-example-shared-1.png)
+
+and cancels the same timer in Rule 2
+
+![timer-shared-cancel](../images/blockly/blockly-timer-shared-cancel.png)
 
 ### Wait for
 
@@ -97,12 +108,14 @@ Though it may not seem to be obvious, the same rule can be retriggered at any ti
 The following code example and the following are provided to understand what exactly happens behind the scenes:
 
 ```javascript
-if (typeof this.timers['MyTimer'] === 'undefined' || this.timers['MyTimer'].hasTerminated()) {
-  this.timers['MyTimer'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
-    })
+if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) {
+  cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () {
+    cache.private.remove('MyTimer');
+  }));
 } else {
-  this.timers['MyTimer'].reschedule(zdt.now().plusSeconds(10));
-}
+  cache.private.get('MyTimer').reschedule(time.ZonedDateTime.now().plusSeconds(10));
+};
+
 ```
 
 **Simple timer-block**
@@ -112,10 +125,12 @@ The simple timer-block generates the code shown underneath the image below.
 ![simple-timer](../images/blockly/blockly-simple-timer.png)
 
 ```javascript
-if (typeof this.timers['simpleTimerBlock'] === 'undefined' || this.timers['simpleTimerBlock'].hasTerminated()) {
-  this.timers['simpleTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
-    })
-}
+if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) {
+  cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () {
+    cache.private.remove('MyTimer');
+  }));
+};
+
 ```
 
 **Retrigger timer-block**
@@ -129,24 +144,27 @@ The retrigger timer-block inserts an additional `else{}` branch into the generat
 In the case of _do nothing_ the `else{}` branch is empty (which turns to be almost equals to the simple-timer).
 
 ```javascript
-if (typeof this.timers['nothingTimerBlock'] === 'undefined' || this.timers['nothingTimerBlock'].hasTerminated()) {
-  this.timers['nothingTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
-    })
+if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) {
+  cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () {
+    cache.private.remove('MyTimer');
+  }));
 } else {
   // do nothing
-}
+};
+
 ```
 
 In the case of _cancel_ the `else{}` branch contains code to cancel the timer.
 
 ```javascript
-if (typeof this.timers['cancelTimerBlock'] === 'undefined' || this.timers['cancelTimerBlock'].hasTerminated()) {
-  this.timers['cancelTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
-    })
+if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) {
+  cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () {
+    cache.private.remove('MyTimer');
+  }));
 } else {
-  this.timers['cancelTimerBlock'].cancel();
-  this.timers['cancelTimerBlock'] = undefined;
-}
+  cache.private.remove('MyTimer').cancel();
+};
+
 ```
 
 In the case of _reschedule_ the `else{}` statement contains code to reschedule the timer - restart the countdown. In the example generated code below:
@@ -157,18 +175,19 @@ In the case of _reschedule_ the `else{}` statement contains code to reschedule t
 - Then timer will be rescheduled for another 10 second countdown, so will execute the code within its block at 15 elapsed seconds.
 
 ```javascript
-if (typeof this.timers['rescheduleTimerBlock'] === 'undefined' || this.timers['rescheduleTimerBlock'].hasTerminated()) {
-  this.timers['rescheduleTimerBlock'] = scriptExecution.createTimer(zdt.now().plusSeconds(10), function () {
-    logger.info('I am doing my job');
-    })
+if (cache.private.exists('MyTimer') === false || cache.private.get('MyTimer').hasTerminated()) {
+  cache.private.put('MyTimer', actions.ScriptExecution.createTimer('MyTimer', time.ZonedDateTime.now().plusSeconds(10), function () {
+    cache.private.remove('MyTimer');
+  }));
 } else {
-  this.timers['rescheduleTimerBlock'].reschedule(zdt.now().plusSeconds(10));
-}
+  cache.private.get('MyTimer').reschedule(time.ZonedDateTime.now().plusSeconds(10));
+};
 ```
 
 ### Cancel Timer
 
 ![cancel-timer.png](../images/blockly/blockly-cancel-timer.png)
+
 _Function_: Cancels the existing named timer, preventing code within the timer block from executing.
 
 ### Timer is Active

configuration/blockly/rules-blockly-uom.md

@@ -27,17 +27,38 @@ The following example block gives a good idea of what can be done with the Unit
 
 ### Unit of Measurement Blocks
 
-These blocks allow you to add, substract, multiply and divide measurements, which include a [**unit**](docs/concepts/units-of-measurement.html#list-of-units) of measurement which is also called a Quantity Type, as well as comparing values against each other.
+These blocks allow you to convert to, add, substract, multiply and divide measurements, which include a [**unit**](docs/concepts/units-of-measurement.html#list-of-units) of measurement which is also called a Quantity Type, as well as comparing values against each other.
 
-## Quantity Block
+### Smart block input type handling
+
+Note that the block is smart enough to either take either one of the three blocks
+
+- "get item block" (which returns the whole Item object and from which the block retrieves state value)
+- "get state item block" (which returns the Item state and from which the block retrieves state value)
+- "item block" (which returns only the name of the Item and from which the block retrieves quantity state of the Item)
+
+or you can directly access the to retrieve the quantity state.
+
+![uom-smart-input-handling](../images/blockly/uom_block_smart_input.png)
+
+Blockly cannot detect the type that is contained in a variable so it expects an item object.
+This allows to iterate over a group of item members which returns a list of item objects:
+
+![uom-#-var](../images/blockly/blockly-quantity-loop-var.png)
+
+This approach is valid for all blocks in this section except _Quantity Conversion_ which expects a Quantity.
+
+## Quantity Blocks
 
 A _Quantity_ is the combination of a value and a unit of measurement, which means that the blocks require a _Quantity_ as an input and generate a _Quantity_ as an output.
 Even though the quantity block looks similar to the standard text block it actually wraps a string into a _Quantity_ type.
 
 _Function:_ The following block takes a string of "10 W" (10 Watts) and converts into a quantity of 10 W which then can be used for computations.
 Instead of using a constant string, the block can also take the output of an item or a variable and convert it into a quantity.
+The second block below allows easier handling in some special cases where you like to supply value and unit seperately.
 
 ![blockly-quantity](../images/blockly/blockly-quantity.png)
+![blockly-quantity-unit](../images/blockly/blockly-quantity-with-unit.png)
 ![blockly-quantity-temperature-item](../images/blockly/blockly-quantity-temp-item.png)
 
 ### Quantity computation
@@ -49,10 +70,14 @@ _Function:_ The block allows to compute the following operations with two quanti
 - division
 - multiplication
 
-It only takes a [quantity block](#quantity-block) as an input and also returns a quantity as an output
+It only takes a [quantity block](rules-blockly-uom.html#quantity-blocks) as an input and also returns a quantity as an output.
 
 ![blockly-quantity-multiplication](../images/blockly/blockly-quantity-multiplication.png)
 
+Due to the smart type detection even this short form works as expected:
+
+![blockly-quantity-smart-computation](../images/blockly/blockly-quantity-smart-computation.png)
+
 Amazingly, this multiplication results into the right quantity of 100 W².
 
 ### Quantity Comparison
@@ -65,6 +90,10 @@ The following shows how it can be used in an if-statement:
 
 ![blockly-quantity-comparison-if](../images/blockly/blockly-quantity-comparison-if.png)
 
+More examples:
+
+![blockly-quantity-comparison-examples](../images/blockly/blockly-quantity-comparison-examples.png)
+
 ### Quantity Conversion
 
 _Function:_ The block provides the conversion from one quantity to another.
@@ -73,6 +102,10 @@ _Function:_ The block provides the conversion from one quantity to another.
 
 The result of that operation would be 0.01 kW.
 
+The following examples show how to use it with an Item:
+
+![blockly-quantity-conversion-item](../images/blockly/blockly-quantity-conversion-item.png)
+
 ## Return to Blockly Reference
 
 [return to Blockly Reference](index.html#items-and-things)