From 14422a8a6b62480063a0cb9e65d4a13a3aac6023 Mon Sep 17 00:00:00 2001 From: J-N-K Date: Sun, 4 Dec 2022 13:56:40 +0100 Subject: [PATCH] Documentation for SCRIPT transformation (#1940) * Documentation for SCRIPT transformation Signed-off-by: Jan N. Klug * improvement Signed-off-by: Jan N. Klug * move to correct location Signed-off-by: Jan N. Klug * Apply suggestions from code review Signed-off-by: Jerome Luckenbach Signed-off-by: Jan N. Klug Signed-off-by: Jerome Luckenbach --- addons/transformations.md | 48 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/addons/transformations.md b/addons/transformations.md index 44d954e6f..0a71726ee 100644 --- a/addons/transformations.md +++ b/addons/transformations.md @@ -59,6 +59,54 @@ Transformation files need to be placed in the directory `$OPENHAB_CONF/transform Transformations can be associated with channels, working on data being passed between bindings and Items. See [profile documentation]({{base}}/configuration/items.html#profiles) for more detail. To keep these examples simple, the contents of the referenced files `window_esp.map` and `convert-C-to-F.js` were left out. + +## `SCRIPT` Transformation + +The `SCRIPT` transformation is available from the framework and needs no additional installation. +It allows transforming values using any of the available scripting languages in openHAB (JSR-223 or DSL). + +The script needs to be placed in the `$OPENHAB_CONF/transform` folder with an extension `.script` regardless of the actual script type. +When referencing a transformation, the script type must be prepended to the filename (e.g. `dsl:stringlength` for the DSL version of `stringlength.script`). +Please note that you cannot have transformations with the same name and different languages as the file-extension is always `script`. + +The input value is injected into the script context as a string variable `input`. +The result needs to be returned from the script, it can have be `null` or value of type that properly implements `.toString()`. +Additional parameters can be injected in the script by adding them to the script identifier in URL style (`js:scale?correctionFactor=1.1÷r=10` would also inject `correctionFactor` and `divider`). + +The examples show a simple transformation with the same functionality for some languages. +It takes the length of the input string and e.g. returns `String has 5 characters`. + +:::: tabs + +::: tab DSL + +The script-prefix is `dsl`. + +```java +var returnValue = "String has " + input.length + " characters" + +returnValue +``` + +::: + +::: tab Nashorn JS + +The script-prefix is `js` + +```java +(function(data) { + var returnValue = "String has " + data.length + " characters" + return returnValue +})(input) +``` + +::: + +:::: + +Currently the `SCRIPT` transformation is not available as profile. + More details regarding this and other Transformation services can be found in the individual transformation articles linked below. ## Available Transformations