diff --git a/configuration/blockly/index.md b/configuration/blockly/index.md index edb03aa26..fee206f0a 100644 --- a/configuration/blockly/index.md +++ b/configuration/blockly/index.md @@ -4,7 +4,7 @@ title: Rules Blockly --- -# Blockly Reference 33 +# Blockly Reference One of the core feature that OpenHAB provides is writing rules to allow specific behaviour with the home automation system. The usual way of developing rules is by coding them like described in the [Textual Rules](/docs/configuration/rules-dsl.html). @@ -32,22 +32,25 @@ All of these provide general functionality that is not specific to openHAB itsel However, to leverage the full capabilities more than *50 specific blocks* have been provided that are tailored for easy access of openHAB's capabilities. 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. -It should also be mentioned that each of the blocks do have a context sensitive menu which appears upon a right click on the block itself. - -**Block context menu** - -![blockly-context.png](../images/blockly/blockly-contextmenu.png) **Looking for help** -A special mention should go towards the **Help** entry that links to a resource that is usually very helpful to understand the context of that particular block. +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. +To retrieve the particular help for a block right click on a block to open the context menu and click on the **help**-entry: + +![context-help](../images/blockly/blockly-context-help.png) + +There is also a help-button available in each section that links to the documentation of the whole section. + +![main-help-button](../images/blockly/blockly-main-help.png) + Please read this information first before asking questions in the forum. *In case you ask for help please always post the respective code that is being generated.* ## Before using blockly Please visit [Getting started with openHAB Blocklies](rules-blockly-before-using.html) before asking questions in the forum -## Blocks +## Blocks Overview ### Items and Things @@ -71,7 +74,7 @@ See [Timers and Delays](rules-blockly-timers-and-delays.html) section. ### Date Handling Date blocks are used as input parameters for other blocks. -At the moment some of these blocks are found in the ephemeris section, whilst others are found in the persistence section - they may be equally useful for both. These blocks are *typed* to assure correct connection to other blocks. +Some of these blocks are used by ephemeris blocks, whilst others are used in the persistence section. Therefore blocks are *typed* to assure correct connection to other blocks. [![Date Handling](../images/blockly/blockly-date-handling1-small.png "Dates part 1") ](rules-blockly-date-handling.html) [![Date Handling](../images/blockly/blockly-date-handling2-small.png "Dates Part 2") diff --git a/configuration/blockly/rules-blockly-before-using.md b/configuration/blockly/rules-blockly-before-using.md index bc3eda7c3..27d32146a 100644 --- a/configuration/blockly/rules-blockly-before-using.md +++ b/configuration/blockly/rules-blockly-before-using.md @@ -85,7 +85,43 @@ All methods reveal the following folders - Press `Ctrl-s` (Windows) or `Command-s` (MacOS) to save your rule - 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 -- Click on ![showcode](../images/blockly/blockly-showcode.png) on the lower right to see the generated code (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) + +### Block context menu + +It should also be mentioned that each of the blocks do have a context sensitive menu which appears upon a right click on the block itself. + +![blockly-context.png](../images/blockly/blockly-contextmenu.png) + +- **Duplicate**: Clones the block +- **Add comment**: Adds a comment to the block +- **Inline Inputs** / External inputs: Switches between horizontal or vertical alignment of inputs + +Inline: +![inline-inputs](../images/blockly/blockly-inputs-inline.png) + +External: +![external-inputs](../images/blockly/blockly-inputs-external.png) + +- **Collapse (expand) block**: Shrinks the block to get a better overview + +Normal block view: +![expanded-block](../images/blockly/blockly-expanded.png) + +Collapsed view: + +![collapsed-block](../images/blockly/blockly-collapsed.png) + +- **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) + +### Zoom the workspace + +The following controls allow the workspace to be zoomed: + +![workspace-zoom-controls](../images/blockly/blockly-zoom.png) + +Pinching on a tablet or a touch bar also allows convenient zooming of the workspace. ## Use Frontail for viewing log files diff --git a/configuration/blockly/rules-blockly-date-handling.md b/configuration/blockly/rules-blockly-date-handling.md index f390ee12f..889852453 100644 --- a/configuration/blockly/rules-blockly-date-handling.md +++ b/configuration/blockly/rules-blockly-date-handling.md @@ -81,7 +81,7 @@ The time is set to `00:00:00`. Type: *ZonedDateTime* This block will return the date as *ZonedDateTime* based on the given String. -The String may be one of the following formats (since 3.3.0M6 the following formats are supported) +The String may be one of the following formats (since 3.3) the following formats are supported) - yyyy-MM-dd - yyyy-MM-dd HH:mm @@ -117,7 +117,7 @@ Tip: if you want to create a datetime with your time zone use the "copy of"-bloc ### Create Datetime based on a specific date ("Copy Of") -since 3.3.0M6 +since 3.3 ![date-copy-of-overview](../images/blockly/blockly-date-copy-of-overview.png) @@ -197,7 +197,7 @@ This variable is then used as the value to amend the lastUpdatedTime of an item ### Datetime from item -since 3.3.0M6 +since 3.3 ![datetime-from-item](../images/blockly/blockly-datetime-from-item.png) @@ -215,7 +215,7 @@ Type: *String* Returns the String representation of a given *ZonedDateTime*-block, with or without the time. -since 3.3.0M6: also returns the same datetime format that is used by openHAB itself +since 3.3: also returns the same datetime format that is used by openHAB itself **Example** @@ -233,7 +233,7 @@ The output in the log will be. ### Date Comparison -since 3.3.0M6 +since 3.3 ![date-comparison](../images/blockly/blockly-date-comparison.png) @@ -246,7 +246,7 @@ Returns true/false based on the comparison ### Date Comparison Between -since 3.3.0M6 +since 3.3 ![date-comparison-between](../images/blockly/blockly-date-comparison-between.png) @@ -259,7 +259,7 @@ Returns true/false based on the comparison ### Get part of datetime -since 3.3.0M6 +since 3.3 ![date-getpartof](../images/blockly/blockly-date-unit-of.png) @@ -269,7 +269,7 @@ Returns the selected part of the datetime as a number. ### Get difference between datetimes -since 3.3.0M6 +since 3.3 ![date-getdifference](../images/blockly/blockly-date-difference.png) diff --git a/configuration/blockly/rules-blockly-items-things.md b/configuration/blockly/rules-blockly-items-things.md index 46133a870..0e86e94fe 100644 --- a/configuration/blockly/rules-blockly-items-things.md +++ b/configuration/blockly/rules-blockly-items-things.md @@ -4,8 +4,12 @@ title: Rules Blockly - Items & Things --- +# Item & Things + [return to Blockly Reference](index.html#items-and-things) +## Introduction + *Items* and *Things* are the [major entities of openHAB](https://www.openhab.org/docs/concepts/) to control and monitor the home. These can be accessed via the "Items & Things" section of the [Blockly Toolbox](/docs/configuration/index.html#blockly-toolbox). diff --git a/configuration/blockly/rules-blockly-logging.md b/configuration/blockly/rules-blockly-logging.md index 2820f0830..1ac31fa1c 100644 --- a/configuration/blockly/rules-blockly-logging.md +++ b/configuration/blockly/rules-blockly-logging.md @@ -39,7 +39,7 @@ These blocks enable arbitrary content to be published to the [openHAB log](https - debug - trace -Since OpenHAB 3.3.0M6: The block attached to the log-block is not restricted to a string type block anymore +Since 3.3: The block attached to the log-block is not restricted to a string type block anymore ### Print Statement diff --git a/configuration/blockly/rules-blockly-run-and-process.md b/configuration/blockly/rules-blockly-run-and-process.md index 0b9161931..9d4d716d6 100644 --- a/configuration/blockly/rules-blockly-run-and-process.md +++ b/configuration/blockly/rules-blockly-run-and-process.md @@ -166,7 +166,7 @@ Provides the possibility to inject any ECMAScript at a given position. This should be used in cases when Blockly does not provide the desired functionality. Use with diligence. -### Example: +### Example ![inline-script-example](../images/blockly/blockly-inline-script-example.png) diff --git a/configuration/blockly/rules-blockly-timers-and-delays.md b/configuration/blockly/rules-blockly-timers-and-delays.md index 5bd92e66b..b076c5e2d 100644 --- a/configuration/blockly/rules-blockly-timers-and-delays.md +++ b/configuration/blockly/rules-blockly-timers-and-delays.md @@ -70,7 +70,7 @@ An example is as follows: ![reschedule-timer-example1](../images/blockly/blockly-reschedule-timer-example1.png) -Setting up an endless timer in teh above way is not recommended. The example shown below will stop rescheduling after 3 doorbell rings. +Setting up an endless timer in the above way is not recommended. The example shown below will stop rescheduling after 3 doorbell rings. ![reschedule-timer-example2](../images/blockly/blockly-reschedule-timer-example2.png) @@ -179,6 +179,7 @@ if (typeof this.timers['rescheduleTimerBlock'] === 'undefined' || this.timers['r ### Timer is Running ![timer-is-running](../images/blockly/blockly-timer-is-running.png) + *Function*: returns `true` if the code *within the timer block* is currently running - i.e. the countdown has finished, and the code within the timer block is currently executing. This event will usually only last a few milliseconds, and you’d be (un)lucky to catch it when your rule retriggers. ### Timer has terminated diff --git a/configuration/images/blockly/blockly-afterperiod-timer-example.png b/configuration/images/blockly/blockly-afterperiod-timer-example.png index 1bdd2fe6b..0f39e1eb9 100644 Binary files a/configuration/images/blockly/blockly-afterperiod-timer-example.png and b/configuration/images/blockly/blockly-afterperiod-timer-example.png differ diff --git a/configuration/images/blockly/blockly-collapsed.png b/configuration/images/blockly/blockly-collapsed.png new file mode 100644 index 000000000..f8d74c1e8 Binary files /dev/null and b/configuration/images/blockly/blockly-collapsed.png differ diff --git a/configuration/images/blockly/blockly-context-help.png b/configuration/images/blockly/blockly-context-help.png new file mode 100644 index 000000000..3f09358fa Binary files /dev/null and b/configuration/images/blockly/blockly-context-help.png differ diff --git a/configuration/images/blockly/blockly-date-difference.png b/configuration/images/blockly/blockly-date-difference.png index 2113f3cdc..cc962c81a 100644 Binary files a/configuration/images/blockly/blockly-date-difference.png and b/configuration/images/blockly/blockly-date-difference.png differ diff --git a/configuration/images/blockly/blockly-date-unit-of.png b/configuration/images/blockly/blockly-date-unit-of.png index d41a5df45..86f98b17d 100644 Binary files a/configuration/images/blockly/blockly-date-unit-of.png and b/configuration/images/blockly/blockly-date-unit-of.png differ diff --git a/configuration/images/blockly/blockly-edit-screen.png b/configuration/images/blockly/blockly-edit-screen.png index 19bd8ca5e..79b610f49 100644 Binary files a/configuration/images/blockly/blockly-edit-screen.png and b/configuration/images/blockly/blockly-edit-screen.png differ diff --git a/configuration/images/blockly/blockly-expanded.png b/configuration/images/blockly/blockly-expanded.png new file mode 100644 index 000000000..088ade32f Binary files /dev/null and b/configuration/images/blockly/blockly-expanded.png differ diff --git a/configuration/images/blockly/blockly-inputs-external.png b/configuration/images/blockly/blockly-inputs-external.png new file mode 100644 index 000000000..598bd6d09 Binary files /dev/null and b/configuration/images/blockly/blockly-inputs-external.png differ diff --git a/configuration/images/blockly/blockly-inputs-inline.png b/configuration/images/blockly/blockly-inputs-inline.png new file mode 100644 index 000000000..a35b5aaec Binary files /dev/null and b/configuration/images/blockly/blockly-inputs-inline.png differ diff --git a/configuration/images/blockly/blockly-items-and-things-small.png b/configuration/images/blockly/blockly-items-and-things-small.png index c0fdf403d..6edbcc389 100644 Binary files a/configuration/images/blockly/blockly-items-and-things-small.png and b/configuration/images/blockly/blockly-items-and-things-small.png differ diff --git a/configuration/images/blockly/blockly-items-and-things.png b/configuration/images/blockly/blockly-items-and-things.png index 3e16eb059..cd5dba8eb 100644 Binary files a/configuration/images/blockly/blockly-items-and-things.png and b/configuration/images/blockly/blockly-items-and-things.png differ diff --git a/configuration/images/blockly/blockly-main-help.png b/configuration/images/blockly/blockly-main-help.png new file mode 100644 index 000000000..464a8f995 Binary files /dev/null and b/configuration/images/blockly/blockly-main-help.png differ diff --git a/configuration/images/blockly/blockly-workspace-showblocks.png b/configuration/images/blockly/blockly-workspace-showblocks.png new file mode 100644 index 000000000..2c6e54cf5 Binary files /dev/null and b/configuration/images/blockly/blockly-workspace-showblocks.png differ diff --git a/configuration/images/blockly/blockly-workspace-showcode.png b/configuration/images/blockly/blockly-workspace-showcode.png new file mode 100644 index 000000000..a7ce8ec7f Binary files /dev/null and b/configuration/images/blockly/blockly-workspace-showcode.png differ diff --git a/configuration/images/blockly/blockly-zoom.png b/configuration/images/blockly/blockly-zoom.png new file mode 100644 index 000000000..b0d73dad4 Binary files /dev/null and b/configuration/images/blockly/blockly-zoom.png differ