[jsscripting] Refine file-based vs. UI-based labelling

[florian-h05]

The merge of #19019 has kicked off a discussion about labelling of UI-based and file-based scripts. I agree that the current naming is not technically correct and not optimal, but it shouldn't be too technical as well for the users.

I think file-based is problematic as well, as that's not really the criteria. "Standard rules" could work, but I would rather emphasize what is "non-standard" about those aren't. I think the whole thing has been "simplified" so much that I'm not sure that the criteria always are the same. I would prefer if things were referred to according to what they actually are.

I suspect that most often the difference is between SimpleRule implementations and "other rules". In a development context, I think SimpleRule should be an acceptable description, but if the term is user-facing, that might not be very helpful, since the use of SimpleRule is usually hidden from them via the helper libraries. As a consequence, they probably have no idea what a SimpleRule is. Preferably, a term that makes sense for the scripting language in question, e.g. jsscripting, could be used. I don't know what you call things, but I know that you have something called RuleBuilder or similar... and that it's not the same as "a normal JS rule"? I'd think that you should have some name for rules using the helper library in such a way that they end up being SimpleRules?

I don't know how it works in jsscripting since I can't get GraalVM to work under Eclipse as I've mentioned before, but I know that in Ruby for example, you can create rules with or without using the helper library. So, you can actually create "non-SimpleRules" (FullRules?) using Ruby via JSR223 as well. Most people don't do it, because using the helper library is easier, but you can if you have a reason to. Such a rule has certain advantages, it can be duplicated to a managed rule from the UI for example.

So, I think the term should depend on the context, and should strive to describe what "actually matters" in that context. In this context, "wrap standard rule scripts" would probably be a reasonable description.

If you look at isUiBasedScript() in this PR, what it actually checks is whether it's a transformation. So, the name is clearly misleading. I would rename it isTransformation() and then negate the evaluation. So, there are actually no measure here to not affect SimpleRule based rules. The Action of a SimpleRule is what's special, you only have one Action, and that Action only exists as compiled bytecode in memory. So, you will never encounter such an Action as a "script" that is served to the jsscripting add-on, which is why you don't really need to do anything to prevent it from being wrapped. If you want to add a Condition to a SimpleRule, you would be affected. SimpleRules are only "special" when it comes to the one Action they have, Triggers and Conditions follow the rules of a standard rule. So, the condition from a SimpleRule would be wrapped too. That said, I don't even know if the helper library supports Conditions, I have the impression that Conditions are largely ignored by the scripting add-ons, and that the evaluations that should be done in a Condition is usually done once the Action has been fired instead, aborting the Action if the conditions aren't right. That's not how it's supposed to work though, so that's also somewhat of an "abuse", but that's another matter. I'm just saying this to explain why I don't expect many to come "into contact with" this Condition situation for rules created through scripting add-ons.

Originally posted by @Nadahar in #19019 (comment)

[florian-h05]

@Nadahar I created an issue for this, discussing in closed PRs always is risky, I already lost track of this PR and that poses the risk I totally forget about that topic.

[Nadahar]

I think it needs to be discussed/figured out, but I don't have any "ready to go suggestion" for exactly how it should be handled. Giving it some focus and making minds start processing how it could be solved might be all we can achieve right now, unless of course somebody else already have some great ideas.

[florian-h05]

I have changed the method names in the code in #19443, please have a look and give feedback.

[florian-h05]

openhab/openhab-js#492 contains further changes to remove the UI-based term.

The question is now, how to proceed with the remaining UI-based in the openhab-js (and thus JS Scripting) README?

[Nadahar]

The question is now, how to proceed with the remaining UI-based in the openhab-js (and thus JS Scripting) README?

I don't have any answers, as I don't have the overview over where these terms are used and what it's reasonable to replace them with. What is the challenge, to find suitable replacement terms, or to find where they are used?

[florian-h05]

Find a suitable replacement.
I can for example replace all „UI-based …“ occurrences with „Script Actions & Conditions“.
Do you think it is clear what is meant if I describe those in the docs.

[Nadahar]

Technically, "Script Actions & Conditions" or "Scripted Actions & Conditions" is correct, but it's hard to know if the distinction is clear enough. I'm not sure where the majority of this content is, some are in labels and description in the UI itself, and some is here: https://github.com/openhab/openhab-addons/blob/main/bundles/org.openhab.automation.jsscripting/README.md

But, there are probably other places too. I took a quote from the README.md file to get an idea:

This allows the use of items, actions, cache and other APIs from the UI without the need to explicitly import them using require().
This functionality can be disabled for users who prefer to manage their own imports via the add-on configuration options:

• Only inject the openhab-js namespaces globally for UI-based rules and scripts (recommended and default).
• Inject the openhab-js namespaces globally for all scripts, including file-based rules and transformations.
• Disable injection of the openhab-js namespaces everywhere, which means you need to import the library using require() in every script that uses it.

I think that part of making the distinction should be done "on the other side" as well, so instead of "file-based rules" it should be "script-created rules", @JSRule and RuleBuilder rules or something like that. But, since you made it possible to make "scripted actions and conditions" with @JSRule as well, that distinction won't work either. The real distinction here is SimpleRule or not, but we can't use that, because it won't mean anything to the users. I'm not sure exactly what terms that fit the best here, but they should probably be used consistently and perhaps get their own little "defining section" in the docs, where it is explained in more detail what is what..?

Regarding transformations - can you build them using "helper library annotations" as well, or are they all standalone scripts? If they are standalone, they are in a way closer to "scripting based actions and conditions" than SimpleRules, but if you can make them the same way as rules, it all gets very blurry.

[florian-h05]

I think that part of making the distinction should be done "on the other side" as well, so instead of "file-based rules" it should be "script-created rules"

All the content about "file-based rules" applies to the whole script file and only if you are in a script file, so file should be in the name. Though it is rather "Script files" than file-based rules, and JSRule is in the context of its "creator" by default so it has the same behaviour. But what the add-on actually checks when making the behavioural difference is: Script Condition, Script Action, Transformation or in file.
That makes it a bit more difficult, as for Scripted Actions/Conditions we are inside the rule, for script files we are both outside and inside a rule.

But, since you made it possible to make "scripted actions and conditions" with @JSRule as well, that distinction won't work either.

I think that's quite a special case that most users won't care about, so it shouldn't affect the overall term too much.

perhaps get their own little "defining section" in the docs, where it is explained in more detail what is what..?

That would help regardless of the actual terms chosen, good idea.

So what about: "Script files", "Script Actions & Conditions" & "Transformations"? We would then have "Rules created from script files" and their behaviour depending on the dedicatedContext option of JSRule, and "Rules created in Main UI" as the most important example for the use of "Script Actions & Conditions".

Regarding transformations - can you build them using "helper library annotations" as well, or are they all standalone scripts?

They typically don't use the helper library and also aren't build with it.
Transformations are standalone scripts in the $OPENHAB_CONF/transform directory or added through the UI (Settings -> Transformations).
I just have to consider them as another environment where JS Scripting can be used in.

[Nadahar]

So what about: "Script files", "Script Actions & Conditions" & "Transformations"? We would then have "Rules created from script files" and their behaviour depending on the dedicatedContext option of JSRule, and "Rules created in Main UI" as the most important example for the use of "Script Actions & Conditions".

Sounds good to me.

[florian-h05]

So, I have just updated the README. Remining is to change the labels and descriptions of the add-on config parameters, will do that next.

[florian-h05]

Add-on PR: #19635