Documentation for SCRIPT transformation (#1940)

* Documentation for SCRIPT transformation

Signed-off-by: Jan N. Klug <github@klug.nrw>

* improvement

Signed-off-by: Jan N. Klug <github@klug.nrw>

* move to correct location

Signed-off-by: Jan N. Klug <github@klug.nrw>

* Apply suggestions from code review

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

Signed-off-by: Jan N. Klug <github@klug.nrw>
Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

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&divider=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