[blockly] Document all new changes for 4.0 (#2017)

* [blockly] document all new changes for 4.0

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

* fix linting

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

* Apply suggestions from code review

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

---------

Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>
Co-authored-by: Jerome Luckenbach <github@luckenba.ch>

configuration/blockly/index.md

@@ -27,6 +27,38 @@ However, to leverage the full capabilities more than _50 specific blocks_ have b
 This section provides a detailed description of the specific blocks and provides examples on how to use them. Note that some of the blocks (like voice, streaming or notifications) need some special setup within openHAB  - in these case links to the respective documentation is provided.
 Also see this ![youtube](../images/blockly/youtube-logo-small.png) [Intro](https://youtu.be/EdllUlJ7p6k?t=295) Quick Intro Blockly Rules
 
+## Blockly is a code generator or how the 🦏 found the holy Grail
+
+### Some history
+
+Even though you may not notice it directly, the blocks are eventually used to automatically create code that can run on the openHAB server.
+Please watch the ![youtube](../images/blockly/youtube-logo-small.png) video [Blockly as an ECMA-Script code generator](https://youtu.be/EdllUlJ7p6k?t=1739) for a live demo.
+The code that is generated can be viewed when clicking the button ![showcode](../images/blockly/blockly-workspace-showcode-small.png) on the lower right corner of the blockly editor.
+
+In general, the code that Blockly generates is JavaScript (aka ECMAScript) which exists in several flavours or versions.
+The ECMAScript version that is used by Blockly in **openHAB 3** is **ECMAScript 5.1** and it is run by a component named **NashornJS** 🦏. [Nashorn JS](https://www.oracle.com/technical-resources/articles/java/jf14-nashorn.html) itself was part of Java until version 14 when it was dropped.
+The generated rule code is run within the Java runtime (also known as JVM) on the openHAB server and as openHAB 4 has moved to Java 17, the old ECMAScript 5.1 is not directly available anymore within the JVM via Nashorn.
+A replacement for the Nashorn JS is **GraalJS** ("the holy grail"), which is currently running **ECMAScript 2022** and therefore supports all modern JavaScript features, like arrow functions.
+[**GraalJS**](https://github.com/oracle/graaljs) is already available in openHAB 3 when the [JS Scripting Addon](https://www.openhab.org/addons/automation/jsscripting/) is installed.
+
+::: tip
+
+Please convert your old rules as quickly as possible because only with GraalJS you can leverage the openHAB JavaScript library (aka _openhab-js_) in Blockly.
+Using this library you can not only create much simpler code, it also allows **new functionality** that is not available with Nashorn.
+**Note that some blocks are only available with the openhab-js library on GraalJS.**
+
+:::
+
+### openHAB 3 / openHAB 4 - Migration
+
+This has several implications:
+
+- From openHAB 4 on, the default script engine is GraalJS when Blockly creates new scripts
+- If you still want to run Blockly rules that were created in openHAB3 without changing them (see below) you can install an automation plugin for Nashorn which could provide backwards compatibility until you have converted all rules.
+After installation both old code and new code can run in openHAB4.
+- **To convert a rule that was created in openHAB 3 (NashornJS) to a new rule based on GraalJS for openHAB 4 simply open the rule once in openHAB 4 and save it - that's it.**
+- After all rules have been converted, please uninstall the Nashorn addon to save memory.
+
 ## Looking for help
 
 A special mention should go towards the **Help** entry in a block context menu [right click on any block](rules-blockly-before-using.html#block-context-menu) that links to a resource that is usually very helpful to understand the context of that particular block.
@@ -44,7 +76,7 @@ Also there is a good  intro about that topic can be viewed at ![youtube](../imag
 
 ## Before using blockly
 
-Please visit [Getting started with openHAB Blocklies](rules-blockly-before-using.html) before asking questions in the forum
+Please visit [Getting started with openHAB Blocklies and creating a rule](rules-blockly-before-using.html) before asking questions in the forum.
 
 ## Blockly Youtube Tutorials
 
@@ -121,6 +153,22 @@ This chapter explains what these blocks do, sometimes displaying generated code
 
 See [Timers and Delays](rules-blockly-timers-and-delays.html) section.
 
+### Voice and Multimedia
+
+This section deals with _playing or streaming audio_ to an audio sink e.g a speaker or _saying a text_ via using any Text-to-Speech API (e.g. Google's API)
+
+[![Voice and Multimedia](../images/blockly/blockly-voice-and-multimedia-small.png "Voice and Multimedia")
+](rules-blockly-voice-and-multimedia.html)
+
+See [Voice and Multimedia](rules-blockly-voice-and-multimedia.html) section.
+
+### Units of Measurements
+
+[![Units of Measurement](../images/blockly/blockly-uom-small.png "Units of Measurement")
+](rules-blockly-uom.html)
+
+See [Units of Measurement](rules-blockly-uom.html) section.
+
 ### Date Handling
 
 Date blocks are used as input parameters for other blocks.
@@ -142,15 +190,6 @@ For example, a way to determine if today is a weekend, a bank holiday, someone
 
 See [Ephemeris](rules-blockly-ephemeris.html) section.
 
-### Voice and Multimedia
-
-This section deals with _playing or streaming audio_ to an audio sink e.g a speaker or _saying a text_ via using any Text-to-Speech API (e.g. Google's API)
-
-[![Voice and Multimedia](../images/blockly/blockly-voice-and-multimedia-small.png "Voice and Multimedia")
-](rules-blockly-voice-and-multimedia.html)
-
-See [Voice and Multimedia](rules-blockly-voice-and-multimedia.html) section.
-
 ### Notifications
 
 For use with your [openHAB cloud](https://www.openhab.org/addons/integrations/openhabcloud/) account, these blocks can be used to send notifications to relevant connected devices.
@@ -206,6 +245,8 @@ This section explains only the blocks that have been added to the standard block
 ](rules-blockly-standard-ext.html)[![openHAB Extensions to the standard](../images/blockly/blockly-lists-dictionary-overview-small.png "openHAB Extensions to the Standard")
 ![lists-overview-concat](../images/blockly/blockly-lists-concatenate.png)
 ](rules-blockly-standard-ext.html)
+[![openHAB Extensions to the standard](../images/blockly/blockly-bitwise.png "openHAB Extensions to the Standard")
+](rules-blockly-standard-ext.html)
 
 See [openHAB Extensions to the standard](rules-blockly-standard-ext.html) section.
 

configuration/blockly/rules-blockly-before-using.md

@@ -37,7 +37,7 @@ In the main UI as an admin you can go to _Help & About_ and will have the differ
 - Finder -> Go -> Connect to Server
   - Enter the username and server name to connect to the openHAB Server
 
-  ![macos-share-1.png](../images/blockly/blockly-openhab-macos-share-1.png)
+  ![macos-share-1](../images/blockly/blockly-openhab-macos-share-1.png)
   - then choose the folder you want to mount
 
   ![macos-share-2](../images/blockly/blockly-openhab-macos-share-2.png)
@@ -83,7 +83,7 @@ Also view ![youtube](../images/blockly/youtube-logo-small.png) [Creating a Block
 - Press `Ctrl-r` (Windows) or `Command-r` (MacOS) to directly run your rule with the trigger
 - Press `Ctrl-d` (Windows) or `Command-d` (MacOS) to disable / enable your rule.
 See the following video on ![youtube](../images/blockly/youtube-logo-small.png) [How to disable Rules](https://youtu.be/hSRfooBKn9A?t=1668)
-- Click on ![showblock](../images/blockly/blockly-workspace-showblocks.png) on the lower right of the bottom toolbar to see the generated code and will transition to ![showcode](../images/blockly/blockly-workspace-showcode.png)(click again to come back to the blocks).
+- **Click on** ![showblock](../images/blockly/blockly-workspace-showblocks.png) **on the lower right of the bottom toolbar to see the generated code** and will transition to ![showcode](../images/blockly/blockly-workspace-showcode.png)(click again to come back to the blocks).
 
 More about the topic of code generation can be viewed at ![youtube](../images/blockly/youtube-logo-small.png) [Blockly as an ECMA-Script code generator](https://youtu.be/EdllUlJ7p6k?t=1739)
 
@@ -93,6 +93,28 @@ It should also be mentioned that each of the blocks do have a context sensitive
 
 ![blockly-context.png](../images/blockly/blockly-contextmenu.png)
 
+#### **Cross-Rule-Copy/Paste**
+
+Sometimes you may want to copy some blocks from one rule to another.
+This is what _Cross-Rule-Copy/Paste_ is for.
+Just mark the block(s) you want to copy, click on _Cross-Rule-Copy_ and then in the destination rule open the context menu and click on _Cross-Rule-Paste_.
+
+![cross-rule-copy](../images/blockly/blockly-cross-rule-copy.png)
+
+Note that you cannot select several blocks at once but only one block to copy.
+
+::: tip Copy multiple blocks
+
+A way to copy multiple blocks at once is to copy a parent block, e.g. a loop block, that contains all the blocks you want to copy together.
+If you want to copy a number of connected blocks at once that do not have a parent block, there is nice trick to do that anyway: drag a function block into the workspace of the source rule, add the blocks to be copied into that function block, copy that function block and then paste it in the destination rule.
+Then in the destination rule just remove the function block that helped you to copy the inner blocks.
+
+:::
+
+Copy and Paste in Action:
+
+![copy-and-paste-in-action](../images/blockly/blockly-cross-rule-copy-and-paste.gif)
+
 - **Duplicate**: Clones the block
 - **Add comment**: Adds a comment to the block
 - **Inline Inputs** / External inputs: Switches between horizontal or vertical alignment of inputs
@@ -115,6 +137,14 @@ Collapsed view:
 - **Disable (enable) block**: Disables the block, so no code is generated and its functionality switched off
 - **Delete**: delete the blocks (this can be reverted via Command/Ctrl-Z)
 
+### Searching the workspace
+
+Sometimes blockly rules become pretty big, and it is hard to find particular blocks in the rule.
+Therefore, a search functionality has been provided by pressing Cmd/Ctrl-F which opens a small search window in the top right (just below the "save"-label).
+After pressing _Enter_ all found blocks that contain the search term are marked in black.
+
+![blockly-search](../images/blockly/blockly-search.png)
+
 ### Zoom the workspace
 
 The following controls allow the workspace to be zoomed:

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

@@ -62,10 +62,9 @@ Function: Gets an **Item** for use in other item related functions
 
 - Clicking 'MyItem' displays a list of **Items** to pick from.
 - Technically this block returns an item _object_, to be used to retrieve specific attributes using other blocks (see below).
-- As this block does not return a String it cannot be directly attached to a log-block, as demonstrated below.
+- In openHAB3 this block does not return a String, so it cannot be directly attached to a log-block, as demonstrated below.
   - **Tip:** Often you do want to retrieve the state, hence use the "Get State of Item"-block below
   - The block returns the item itself.
-If you want to log the items information you can assign it to a variable first and the log the variable.
 
 ![logging-getItem](../images/blockly/blockly-getItem-with-var.png)
 
@@ -133,6 +132,8 @@ If you need an item that has one of multiple tags, then you need to use one bloc
 
 Function: Get either the current name, label, state, category, tags, groups, or type of an item as a String
 
+It requires an [item object](#get-item) to be connected.
+
 These attributes are returned with the following types:
 
 - name: String
@@ -153,9 +154,6 @@ These attributes are returned with the following types:
 
 - type: String
 
-Depending on your openHAB version (pre-3.3) this block may not connect as expected.
-As a workaround attach the block to a variable first, and use the variable in the rest of the script.
-
 ![blockly-getItemAttributes-fix](../images/blockly/blockly-getItemAttributes-fix.png)
 
 **Special handling for Arrays**
@@ -195,9 +193,62 @@ More about that topic can be viewed at ![youtube](../images/blockly/youtube-logo
 - Get the state of _MainSwitch_ and
 - Immediately send it as a command to _F2_Office_Main_Light_
 
-![blockly-sendCommandExample2)](../images/blockly/blockly-sendCommandExample2.png)
+![blockly-sendCommandExample2](../images/blockly/blockly-sendCommandExample2.png)
 Ensure that the receiving item can handle the state of the 'sending' item.
 
+## Item Metadata
+
+The **metadata blocks**  provide an easy way of accessing namespace metadata information both for reading and writing.
+Accessing config metadata on hierarchical levels as well as variable support that allows iteration over computed names is supported (see the examples below).
+
+Note: Metadata blocks are not available for Nashorn but only for GraalJS / JS Scripting.
+
+Here is an _expire_ metadata definition which is visualized as
+
+![metadata-expire](../images/blockly/blockly-metadata-expire.png)
+
+and modelled in YAML as
+
+```yaml
+value: 0h3m0s
+config:
+  ignoreStateUpdates: "true"
+  ignoreCommands: "true"
+with the blocks that can access it:
+
+![blockly-metadata](../images/blockly/blockly-metadata.png)
+
+There a two different type of blocks:
+The value block is the main one for the _value_ of the namespace, which is also directly shown in the MainUI's list of an item's metadata, while the _config_ part holds more complex configuration of that metadata structure below the entry _config_.
+
+The following blocks allow to _change_ the config values in the namespace _expire_:
+
+![blockly-metadata-change](../images/blockly/blockly-metadata-change.png)
+
+Here is a definition of a more complex metadata namespace:
+
+```yaml
+value: ON
+config:
+  ooone: "123"
+  oone:
+    two: "456"
+  one:
+    two:
+      three: "756"
+  field1: 1
+  field2: 2
+  field3: 3
+```
+
+which allows deep hierarchy property access via a configkey-dot-notation like `one.two.three`
+
+![blockly-metadata-config-key.png](../images/blockly/blockly-metadata-config-key.png)
+
+Using variables and loops properties like field1, field2, field3 can even be accessed in a computed way:
+
+![blockly-metadata-loop.png](../images/blockly/blockly-metadata-loop.png)
+
 ## Things
 
 ### Thing

configuration/blockly/rules-blockly-persistence.md

@@ -45,6 +45,7 @@ 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
 - maximum: 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:
 

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

@@ -19,6 +19,30 @@ This section explains only the blocks that have been added to the standard block
 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).
 
+## Math
+
+The Math section mainly consists of standard Blockly blocks.
+Two new math blocks were added for bitwise operations:
+
+### Bitwise operators
+
+_Function:_ The block allows to compute the following operations with two quantities:
+
+- bitwise and &
+- bitwise or |
+- bitwise xor ^
+- bitwise left shift <<
+- bitwise right shift >>
+- bitwise unary right shift >>>
+
+![blockly-bitwise-operators](../images/blockly/blockly-bitwise-operators.png)
+
+### Bitwise invert
+
+_Function:_ The bitwise NOT (~) operator inverts the bits of its operand.
+
+![blockly-bitwise-not.png](../images/blockly/blockly-bitwise-not.png)
+
 ## Text
 
 The Text section is the general section that allows text or string manipulation

configuration/blockly/rules-blockly-uom.md

@@ -0,0 +1,78 @@
+---
+layout: documentation
+title: Rules Blockly - Items & Things
+---
+<!-- markdownlint-disable MD036 -->
+
+# Units of Measurements
+
+[return to Blockly Reference](index.html#items-and-things)
+
+## Introduction
+
+[Unit of Measurements](docs/concepts/units-of-measurement.html) have been a part of openHAB for a long time already and received some major improvements in particular in openHAB 4.0.
+Therefore, to make the usage in blockly easier and allow math computations with measurement units, severals blocks have been added.
+
+Note that these blocks are only available since openHAB 4.0 and are based on JS Scripting / graalJS.
+
+The following example block gives a good idea of what can be done with the Unit of Measurement blocks
+
+![blockly-uom-example](../images/blockly/blockly-uom-example.png)
+
+[[toc]]
+
+## Overview of the Items and Things category
+
+![blockly-uom](../images/blockly/blockly-uom.png)
+
+### 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.
+
+## Quantity Block
+
+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.
+
+![blockly-quantity](../images/blockly/blockly-quantity.png)
+![blockly-quantity-temperature-item](../images/blockly/blockly-quantity-temp-item.png)
+
+### Quantity computation
+
+_Function:_ The block allows to compute the following operations with two quantities:
+
+- addition
+- substraction
+- division
+- multiplication
+
+It only takes a [quantity block](#quantity-block) as an input and also returns a quantity as an output
+
+![blockly-quantity-multiplication](../images/blockly/blockly-quantity-multiplication.png)
+
+Amazingly, this multiplication results into the right quantity of 100 W².
+
+### Quantity Comparison
+
+_Function:_ The block allows to compare two quantities with the following operands which will return a boolean as a result.
+
+![blockly-quantity-comparison](../images/blockly/blockly-quantity-comparison.png)
+
+The following shows how it can be used in an if-statement:
+
+![blockly-quantity-comparison-if](../images/blockly/blockly-quantity-comparison-if.png)
+
+### Quantity Conversion
+
+_Function:_ The block provides the conversion from one quantity to another.
+
+![blockly-quantity-conversion](../images/blockly/blockly-quantity-conversion.png)
+
+The result of that operation would be 0.01 kW.
+
+## Return to Blockly Reference
+
+[return to Blockly Reference](index.html#items-and-things)

configuration/blockly/rules-blockly-value-storage.md

@@ -27,27 +27,46 @@ To check if a value is undefined, use the special "is undefined"-block
 
 ![value-storage-blocks](../images/blockly/blockly-value-storage.png)
 
+### Caching
+
+Since openHAB 4.0 caching functionality was introduced (provided that the rule is using [GraalJS / JS Scripting](/docs/configuration/blockly/#openhab-3-openhab-4-migration)).
+The blocks have the same behaviour like before when set to "private cache" which means that the value is stores in the rule cache.
+When storing a value in the "**shared cache**" the value can be even used beyond the specific rule **in a different rule**.
+
+![value-storage-blocks-cache](../images/blockly/blockly-value-storage-cache.png)
+
 ## Value Storage Blocks
 
 See also the short video part about ![youtube](../images/blockly/youtube-logo-small.png) [Global Value Storage](https://youtu.be/KwhYKy1_qVk?t=2060)
 
 ### Store Value
 
+openHAB 4.0
+![store-value-cache](../images/blockly/blockly-value-store-cache.png)
+
 ![store-value](../images/blockly/blockly-value-store.png)
 
-Function: Stores a value under the key name
+Function: Stores a value under the key name in the specified [cache](#caching).
 
 ### Get Stored Value
 
+Since openHAB 4.0:
+
+![blockly-value-get-cache](../images/blockly/blockly-value-get-cache.png)
+
 ![get-stored-value](../images/blockly/blockly-value-get.png)
 
-Function: Retrieves a stored value by the key name
+Function: Retrieves a stored value by the key name from the specified [cache](#caching).
 
 ### Check if Value is undefined
 
+Since openHAB 4.0:
+
+![get-stored-value](../images/blockly/blockly-value-is-defined-cache.png)
+
 ![value-is-defined](../images/blockly/blockly-value-is-defined.png)
 
-Function: Checks if a value is undefined
+Function: Checks if a value is undefined in the specified [cache](#caching)
 
 ### Example 1: Initialize a key if not set