From 2bb714ade3fd5474244d0a8f5c1da2e0d02bc74a Mon Sep 17 00:00:00 2001 From: Richard Koshak Date: Fri, 18 Jul 2025 10:32:19 -0600 Subject: [PATCH 1/3] Improvements for UI event docs Added rows for `event.event` and `event.payload` to the table. Reworded some of the warnings because manual triggers still have `event`. It's only when a rule calls another rule that the called rule doesn't have `event`. Solves issue #316. Signed-off-by: Richard Koshak --- README.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 62ee72db..9b166932 100644 --- a/README.md +++ b/README.md @@ -138,10 +138,11 @@ See [openhab-js](https://openhab.github.io/openhab-js) for a complete list of fu ### UI Event Object **NOTE**: Note that `event` object is different in UI based rules and file based rules! This section is only valid for UI based rules. If you use file based rules, refer to [file based rules event object documentation](#event-object). -Note that `event` object is only available when the UI based rule was triggered by an event and is not manually run! -Trying to access `event` on manual run does not work (and will lead to an error), use `this.event` instead (will be `undefined` in case of manual run). +Note that `event` object is only available when the UI based rule was triggered by an event and is not called from another rule unless it is passed from the calling rul! +Trying to access `event` in this case does not work (and will lead to an error), use `this.event` instead (will be `undefined` when it does not exist). When you use "Item event" as trigger (i.e. "[item] received a command", "[item] was updated", "[item] changed"), there is additional context available for the action in a variable called `event`. +When a rule is triggered, there is additional context available for the action in a variable called `event`. This table gives an overview over the `event` object for most common trigger types: @@ -152,8 +153,10 @@ This table gives an overview over the `event` object for most common trigger typ | `itemCommand` | sub-class of [org.openhab.core.types.Command](https://www.openhab.org/javadoc/latest/org/openhab/core/types/command) | `[item] received a command` | Command that triggered event | `receivedCommand` | | `itemName` | string | all | Name of Item that triggered event | `triggeringItem.name` | | `type` | string | all | Type of event that triggered event (`"ItemStateEvent"`, `"ItemStateChangedEvent"`, `"ItemCommandEvent"`, ...) | N/A | +| `event` | string | channel based triggeres | Event data publsihed by the triggering channel. | `receivedEvent` | +| `payload` | JSON formatted string | all | Any additional information provided by the trigger not already exposed. "{}" there is none. | N/A | -Note that in UI based rules `event.itemState`, `event.oldItemState`, and `event.itemCommand` are Java types (not JavaScript), and care must be taken when comparing these with JavaScript types: +Note that in UI based rules `event`, and therefore everything carried by `event` are Java types (not JavaScript). Care must be taken when comparing these with JavaScript types: ```javascript var { ON } = require("@runtime") From 8644b41c99ff0614f0a873bf7baff03c5e66411d Mon Sep 17 00:00:00 2001 From: Richard Koshak Date: Fri, 18 Jul 2025 10:37:16 -0600 Subject: [PATCH 2/3] last minute typos and rewording noticed a typo and decided to change some wording. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 9b166932..cca3363c 100644 --- a/README.md +++ b/README.md @@ -138,8 +138,8 @@ See [openhab-js](https://openhab.github.io/openhab-js) for a complete list of fu ### UI Event Object **NOTE**: Note that `event` object is different in UI based rules and file based rules! This section is only valid for UI based rules. If you use file based rules, refer to [file based rules event object documentation](#event-object). -Note that `event` object is only available when the UI based rule was triggered by an event and is not called from another rule unless it is passed from the calling rul! -Trying to access `event` in this case does not work (and will lead to an error), use `this.event` instead (will be `undefined` when it does not exist). +Note that `event` object is only available when the UI based rule was triggered by an event and is not called from another rule! +Trying to access `event` in this case does not work and will lead to an error. Use `this.event` instead (will be `undefined` when it does not exist). When you use "Item event" as trigger (i.e. "[item] received a command", "[item] was updated", "[item] changed"), there is additional context available for the action in a variable called `event`. When a rule is triggered, there is additional context available for the action in a variable called `event`. From 1902eb9a9cc27b18c78380937352afb09720c030 Mon Sep 17 00:00:00 2001 From: Richard Koshak Date: Mon, 21 Jul 2025 11:14:18 -0600 Subject: [PATCH 3/3] Fix typoe found during review Co-authored-by: Florian Hotze Signed-off-by: Richard Koshak --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cca3363c..da67e95d 100644 --- a/README.md +++ b/README.md @@ -153,7 +153,7 @@ This table gives an overview over the `event` object for most common trigger typ | `itemCommand` | sub-class of [org.openhab.core.types.Command](https://www.openhab.org/javadoc/latest/org/openhab/core/types/command) | `[item] received a command` | Command that triggered event | `receivedCommand` | | `itemName` | string | all | Name of Item that triggered event | `triggeringItem.name` | | `type` | string | all | Type of event that triggered event (`"ItemStateEvent"`, `"ItemStateChangedEvent"`, `"ItemCommandEvent"`, ...) | N/A | -| `event` | string | channel based triggeres | Event data publsihed by the triggering channel. | `receivedEvent` | +| `event` | string | channel based triggeres | Event data published by the triggering channel. | `receivedEvent` | | `payload` | JSON formatted string | all | Any additional information provided by the trigger not already exposed. "{}" there is none. | N/A | Note that in UI based rules `event`, and therefore everything carried by `event` are Java types (not JavaScript). Care must be taken when comparing these with JavaScript types: