Blockly 4.1 doc updates (openhab#2201)

* Blockly 4.1 doc updates

Signed-off-by: Stefan Höhn <[email protected]>

* review updates

Signed-off-by: Stefan Höhn <[email protected]>

---------

Signed-off-by: Stefan Höhn <[email protected]>

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

@@ -158,6 +158,21 @@ These attributes are returned with the following types:
 
 ![blockly-getItemAttributes-fix](../images/blockly/blockly-getItemAttributes-fix.png)
 
+**Simplified usage**
+
+Since openHAB 4.1 an optimization was introduced that simplifies the usage:
+
+![blockly-getItemAttributes](../images/blockly/blockly-getItemAttributes-simple.png)
+
+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_
+
+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.
+
 **Special handling for Arrays**
 
 The attributes _groups_ and _tags_ return an Array of entries.

configuration/blockly/rules-blockly-persistence.md

@@ -44,14 +44,15 @@ This method uses a time-weighted average calculation
 - evolution rate: gets the evolution rate of the state of the given Item in percent since a certain point in time (may be positive or negative)
 - 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
-- maximum: gets the sum 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
+- 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
 
 The persistence dropdown allows to select the persistence storage from which the value should be retrieved.

configuration/blockly/rules-blockly-run-and-process.md

@@ -87,6 +87,7 @@ A rule carries contextual information when triggered - this block can retrieve t
 Here is a list of possible values that can be retrieved.
 
 - rule UID - String
+- event available - Boolean
 - event type - String
 - new state of item - String / Number by selection
 - previous state of item - String / Number by selection
@@ -95,6 +96,9 @@ Here is a list of possible values that can be retrieved.
 - triggered channel - String
 - triggered event - String
 
+Note on "event available": All values except _rule UID_ expect an event context to be available.
+Thus, to avoid issues, you can validate that with the _event available_ block in case this is not guaranteed in your rule.
+
 The block adds a selection drop down in case a state or command is returned:
 
 ![blockly-context-number-string](../images/blockly/blockly-context-number-string.gif)

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

@@ -24,6 +24,20 @@ More about conditions can be viewed at ![youtube](../images/blockly/youtube-logo
 The Math section mainly consists of standard Blockly blocks.
 Two new math blocks were added for bitwise operations:
 
+### Quantity Type support
+
+Blockly allows to use Quantity types to do its math operations.
+This means that Quantity States can directly be used as an input for math operation blocks.
+
+Here are some examples for math operations with unit-accompanied values:
+
+![quantity-math-operations](../images/blockly/blockly-math-quantity-operations.png)
+
+Note that there is a special case on min/max if the inputs are not of equal type.
+In this case an error will be shown to the user:
+
+![quantity-math-operations](../images/blockly/blockly-math-quantity-operations-failure.png)
+
 ### Bitwise operators
 
 _Function:_ The block allows to compute the following operations with two quantities:
@@ -49,6 +63,12 @@ The standard block has been extended to provide a rounding function with the abi
 
 ![math-round](../images/blockly/blockly-math-round.png)
 
+### Parse Number
+
+This blocks takes a String floating point number representation and converts it into a Number type block.
+
+![blockly-math-parse-number.png](../images/blockly/blockly-math-parse-number.png)
+
 ## Text
 
 The Text section is the general section that allows text or string manipulation
@@ -92,6 +112,15 @@ A color of r=255, g=255, b=255 would therefore result into #ffffff preceded by a
 Note that typically RGB values are not used within openHAB for color states but instead the Color-Type expects a HSB Type.
 See the special hsb-conversion block below.
 
+Blockly supports the following use cases:
+
+- pick a color to return the value as an RGB type
+- chose a random color as RGB type
+- define an RGB color based on red, green and blue.
+- blend two colors with a ratio - this block can be used to dynamically transition from one color to the other by applying the ratio as a computed value in a rule.
+- calculate the HSB value of the RGB value
+- get hue, saturation or brightness from a HSB Type Color Status of an Item
+
 ### Color Picker
 
 ![color-picker](../images/blockly/blockly-colors-picker.png)
@@ -144,6 +173,16 @@ Example
 
 ![get-hsb-of-example](../images/blockly/blockly-colors-hsbof-example.png)
 
+### Retrieve indidivual HSB values from an Item state
+
+This block allows to retrieve the individual values of an Item’s HSB color state by returning
+
+- Hue,
+- Saturation,
+- or Brightness
+
+![blockly-colors-hsb.png](../images/blockly/blockly-colors-hsb.png)
+
 ## Lists
 
 ![lists-overview](../images/blockly/blockly-lists-dictionary-overview.png)