openhab
Add advanced widget doc page
@ghys Here's a whole new page with advanced topics on components and widgets. Take a look when you get a chance and let me know what you think is missing.
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).
| Name | Link |
|---|---|
| Latest commit | 85187ae34374384b129da4a2f72399741c8a13aa |
| Latest deploy log | https://app.netlify.com/sites/openhab-docs-preview/deploys/635950035cdaa700092f72b8 |
| Deploy Preview | https://deploy-preview-1896--openhab-docs-preview.netlify.app |
| Preview on mobile | Toggle QR Code...Use your smartphone camera to open QR code link. |
To edit notification comments on pull requests, go to your Netlify site settings.
![netlify[bot] avatar](https://avatars.githubusercontent.com/in/13473?v=4 "Published by a pub.dev verified publisher"){kind=small}
Personally I would move the Building Pages: Personal Widgets section to this new page and rename the new page to
Building Custom Widgets.
I was hesitant to move anything over, mostly because I wasn't sure what break made the most sense without leaving Building Pages too short, and this new page too long. But, now that you point it out, I can see the logic of just moving that last Personal Widgets section; I like it better than the little opening line I already have.
Put each sentence on its own line as this simplifies tracking changes.
Sure, hadn't thought of that. Easy enough.
I personally would prefer to capitalize Items as this is an OH term. This is not consistent across the docs, but most newer doc changes capitalize OH terms like Items, Things, ….
I think that's reasonable, I'll try to be more consistent about that myself.
I am not sure if
Any of the OH components that allow widget actions(without the for) is better.
I am aware that my syntax is occasionally somewhat archaic. I have no problem with suggestions updating what I write for the 21st century. :wink:
This improves readability.
This is the most problematic issue. I agree 100% that the spaces in the code improve readability and went back and forth a couple of times while making the first draft.
The problem is, as the tip above the object example points out, the spaces with regards to a colon are actually problematic in yaml. So if we put the spaces in the code to improve readability and a user copies that example directly or just emulates its formatting with their code, it will throw errors instead of working. So which priority is higher here: clarity of the example code or direct usability of the code?
I finally decided on the fully working code just because I felt (with no actual justification) that comments/complaints about "confusing code" would be fewer than comments/complaints about "code in the docs that doesn't work".
So which priority is higher here: clarity of the example code or direct usability of the code?
I wasn‘t aware of this problem, I read about it in the docs but I had never problems with any spaces. Direct usability of the code is the higher priority here, as many people will copy and change from the docs.
I finally decided on the fully working code just because I felt (with no actual justification) that comments/complaints about "confusing code" would be fewer than comments/complaints about "code in the docs that doesn't work".
I see your point, you decided right.
After moving the Personal Widgets section to the new page I thought it made more sense for me to add in a little more basic intro to widgets and put back in a section on OH widgets I had originally written but taken out. So it's now a run through from the very beginning to advanced widget creation.
Let me know if you think the new sections work.
Thanks for all the editing assistance. I've made those changes plus a handful more small edits I've found looking over it fresh in the morning. It should be good to go now.
