-
-
Notifications
You must be signed in to change notification settings - Fork 679
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Added an example of the ScriptAction
preset
#2228
Conversation
✅ Thanks for your pull request to the openHAB documentation! The result can be previewed at the URL below (this comment and the preview will be updated if you add more commits).
To edit notification comments on pull requests, go to your Netlify site configuration. |
✅ Thanks for your pull request to the openHAB documentation! The result can be previewed at the URL below (this comment and the preview will be updated if you add more commits).
To edit notification comments on pull requests, go to your Netlify site configuration. |
You should mention that this is not necessary when using JS Scripting nor jRuby as all of that stuff is handled by the helper libraries. Nashorn JS will work similarly to Groovy apparently. JS Scripting
jRuby
Nashorn JS
But this raises a question. Should everything provided by ScriptExecution be documented here? Id does more than just create timers (i.e. And what about all the other built in actions found here? If ScriptExecution is going to be separately documented then all of them should be. But the content will get pretty redundant I think. Maybe the section should be made generic and show how to import all of these with a couple of examples. I also know that for at least JS Scripting, the classes are just imported directly instead of using the rule presents. I don't know if there is a big difference or preference. |
I don’t see anything besides timers neither on the Moreover, in the That’s why only timers are documented.
As far as I can see (by running test UI script), there’s no The doc page we're talking about states that “The default preset is preloaded, so it does not require importing.”. No other presets are mentioned, I don’t see ‘em imported on practice, and I don’t see anything from these presets is available without importing these presets. |
It might be that Groovy works differently from the other languages. If so, the documentation for stuff that Groovy does differently belongs in the docs for Groovy. I don't know. But anything that goes in the JSR223 Docs needs to be generic and inclusive. You will notice that all the other examples on this page includes most of the supported languages, not just one. It's worth noting that Groovy is indeed missing but that's because all the people who have edited this doc until now don't know Groovy. It's not one of the most used languages and no one has really volunteered over the years to provide good documentation for it. If you do know Groovy, it would be most helpful to add Groovy examples to the other sections. Though that's probably best left for a different PR. |
Fair enough. But no other built-in actions you've mentioned earlier. I'd prefer that someone else who has used Even without describing an interface in all its entirety, I'll consider doc with current additions more complete, hence in a better state than before.
We have a part of the doc about importing presets. It is not marked as specific for any language and not under tab:
If I understand you correctly, you're saying that this is Groovy-specific functionality but, it's in the doc already.
I see this doc with its raw class names and internal details as an overview of the JSR233 scripting mechanism from the openHAB standpoint as a platform, where language specific examples provided as an addition for convenience. I can remove the part where I mention that "preset can be useful for scheduling asynchronous code execution with
I'll consider it. |
Right. Those are on different presets. But if we are going to document https://www.openhab.org/javadoc/latest/org/openhab/core/model/script/actions/package-summary There isn't anything special about And because it would be all quite redundant to document each one individually, I'm proposing making the update here more generic to all of these instead of iterating over each and every one with 90% of the same docs and only the names of the presets/classes/examples changing. Provide the names of the presets and one or two examples and point to https://www.openhab.org/docs/configuration/actions.html for the full list of Actions and how to use them.
No, what I'm saying is that the need to import it manually like you've documented is Groovy specific. All the rest of the languages get it by default, as the documents currently say should happen.
That part too is true for all the languages. What's Groovy specific is you don't just have access to the presets to call these by default like is the case in the other languages (except Nashorn though I'd need to explore more there too as it should be there in the default presets but I've never seen it pulled in that way, it's usually imported using Java.type()). |
Do these actions have their own presets? I can't find them. This PR is not about rules Actions. It's about one particular preset and one particular variable this preset brings into the script context. This preset exists as a part of a JSR223 scripting mechanism of the openHAB platform and isn't special for any scripting language. If some of the scripting language's implementations don't require explicit preset import, so what? It is still there in generic JSR223 code, which this doc is about considering its title. As one can see, in some cache examples there is
That part is under the Groovy tab of examples. Isn't something placed under a language-specific tab considered language-specific? Isn't that why these tabs are there in the first place? If you're saying that there should be tabs for other languages, then sure. I'll be happy to use examples you provided in your first comment. If that wouldn't be enough, then I'd prefer to get more precise examples of what you want to be in the doc, or leave that part for someone who's proficient in scripting using these languages for the openHAB platform. It's rather hard for me to get your point about what this doc is intended to look like. |
@rkoshak Let me know and ping me when you finally feel comfortable to have it merged. |
I would assume so but I don't know where to look. I can't imagine why ScriptExecution would have a preset and the rest wouldn't. There is nothing special about it.
It's only an issue if the only example presented is Groovy. I supplied examples for many of the other languages above. Rules DSL gets what it gets so I'm not sure an example for it is worth anything.
The tabs are to show how to do it in all the supported languages in a way that it doesn't take up pages of space showing each one. If this is something that is only done in Groovy, it should go in the Groovy docs. If it's something universal, there should be examples for most of the languages. |
As far as I understand, context variables for JSR223 are provided by Looking at There's a default context variable So now you know where to look and can do it for yourself.
In my previous comment, I've suggested to add your examples to the relevant tabs:
Would that be enough? |
OK, I wrote a rule to dump all the presets available from the ScriptExtensionProvider. This is Nashorn JS:
We are missing quite a bit more than just the ScriptAction preset which, I still wonder why it even exists given that none of the other Rule Actions are exposed as a preset and there shouldn't be anything special about creating a Timer that warrants a wholly separate preset. Regardless I'd recommend one of these two options.
I can help with 2. I've never used them except for |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the contribution but I wonder if @rkoshak is happy now?
I'm happy with what's been written except for the fact that Rules DSL, JS Scripting and jRuby are missing. Beyond that, fi it's not covered in this PR, an issue needs to be created to add sections for The other examples would be:
|
Do you like me to add these to the PR? |
That would be great! I was trying to figure out how to add them myself and I'm not sure how to go about doing it. |
The Ruby version:
|
@rkoshak no worries, that's what I am here for. 👋 As a maintainer I can add to the PR of the contributor (and there is an easy way to do that by using 'gh pr checkout 2228'. Also since a few weeks you can even run "npm run serve" to build the docs locally to verify the outcome before pushing. @jimtng Note: I had to fix a few markdown issues as well. Please Rich and Jim check my changes. |
Signed-off-by: Oleg Andreych <kjiec4@gmail.com>
Signed-off-by: Oleg Andreych <kjiec4@gmail.com>
Please use my version as is
|
Unfortunately the rebase broke a few things. I need to clean that up first 😱 Let me know if I can merge it. |
Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>
Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>
Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>
Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>
configuration/jsr223.md
Outdated
|
||
```ruby | ||
after(1.second) do | ||
logger.info("Timer ran") |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
logger.info("Timer ran") | |
logger.info("Timer ran") |
Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>
No description provided.