OH3 UI: Some great, some not so great design decisions and prioritizations?

[c_r]

Hi,

I would like to discuss a couple of aspects regarding the design (architecture) of the way the User Interface/Frontend output can be configured in OH3. Although I raise several issues below, please regard this post as a starting point for discussion and for finding solution for issues I (and probably others) have when using OH3. I highly appreciate the great work @ysc and many others have put into making the new release happen!

As a background information: I consider myself as a OH(2) PowerUser who is able and willing to spend many hours/days on configuration, can write extensive and advanced rules, is able to tweak CSS and understand code; I am not a developer who can write full (web applications), but have a good understanding of software architecture and a passion for user experience.

Moving OH3 UI to the next level by using state-of the art frameworks like vue.js and Framework7 (F7), support for creating reusable Custom widgets etc. was definitely the right thing to do. When I saw the presentation in the Openhab Virtual meetup, I was blown away

After I have now tried out OH3 myself and spent more than a full week on getting familiar with the new UI capabilities, I must say I am quite disappointed. I get the impression that many, many new features got implemented, but we missed to get the basics working properly first. I still can see the potential (and some minor things will get fixed over time as usual), but by now I have the feeling that some fundamental aspects are wrong.

Here is my point of view of what does not seem to be right:

1. Blackbox Predefined widgets limit possibilities:
It is mandatory to use certain oh-… widgets and to use them in a certain structure (e.g. rows/cols, cells etc.) which influence (HTML-)structure, design and behaviour. Some aspects of them can be overrriden, but by far not all.
Also, the Predefined widgets are not available as (yaml) source so that they could be used as template and modified according to the user’s needs.
Overall, it is easy to get a first UI with several widgets quickly, but if you seriously think about what’s good UX, you immediatly run into limitations.

2. “Hardcoded” Styles
index.html, Framework7 CSS and JS are hardcoded in OH UI bundle. As a result, there is no easy and reliable way for custom/additional styling or CSS tweaks. Also F7 Plugins might de desirable, but can’t be used.

3. Inline Styles everywhere
Due to the missing option to change the F7 CSS, people start to put all kinds of inline-styles in custom widgets, which is not a good basis to keep your app maintainable or even for exchanging widgets among users.

4. No documentation available
There is no documentation available even explaining the basics (Purpose of available OH Widgets, Layout examples, which way of nesting of components is allowed). I know and highly appreciate the forum thread [wiki] Building Pages in the OH3 UI: documentation draft but I think even when its finalized, this is not sufficient. Rather than developing new UI features I think we should prioritize creating a proper documentation thats suits a major release like OH3.

5. No possibility of UI debugging
Many changes in the YAML lead to blank pages or widgets. In such cases, there are no error messages in the UI or OH logfile (even on loglevel DEBUG). That, combined with a non-existant documentation, makes UI development a rather nerv-wracking exercise.

6. No editing of pages and widgets outside OH Admin UI
The built-in YAML Editor is OK for a few basic changes, but overall it is not very developer friendly and IMHO not suited for larger, more complex layouts. Would be great to use an external editor like VS Code (with Code validation through LSP).

7. No Code versioning
Even more important: there is no way of code-versioning for pages and widgets. No rollback whatsoever possible (except for JSONDB file backup). In OH, I simply use git to version-control all my sitemap, thing, items etc.

8. Limitations/Flaws in using F7, Predefined or Custom widgets, e.g.

• broken f7 components: e.g. try to put a “media” slot inside a f7-list-item component (it does not appear in the HTML output)
• when adding a widget “from model” the widget that is set in the item configuration is used. Any later changes in the item configuration regarding the default widget are not reflected in the UI
• Nesting of Custom Widgets does not seem to be possible (e.g. custom f7-list, into which custom f7-list-items can be added in the visual editor or in yaml code)
• UI styling out of the box not consistent (Cells vs. Cards)
  Update 2021-02-09:
• When using an oh-list-item in a custom widget, the properties of the widget cannot be edited on a page (but only the configuration of the underlying oh-list-item), partly defeating the purpose of a reusable design component.

9. No Demo/Template UI
There does not seem to be templates for pages and Predefined widgets showing all design possibilities of the new UI (except that the demo on www.openhab.org has been relaunched just lately), similar to the F/ reference and Kitchensink. I am wondering how the Predefined widgets have been tested during development (I guess a visual check of all possible configurations of widgets is needed here as well).

10. Insufficient iPhone UI
(same probably applies to Android - not tested). I believe that this problem derives from F7, since there does not seem to be a way to control a flexbox behaviour for displays smaller that 480px wide (e.g. iPhoneX). The result is that if you have a oh-grid-row with multiple oh-grid-cols containing e.g. Listcards (which is fine to be displayed side-by-side on tablet), you can’t have the cols/Listcards wrap underneath each other with 100% width on an iPhone. The only way out seems to be creating separate pages for tables and phones, which does not make sense in a Responsive SPA.
Update 2021-02-09:
According to the new docs, you can set attributes to control the default width, and for other screensizes (xsmall, small etc.). This seems to be OK (however, it would have been simpler to use the (already documented and working) f7 CSS classes ( rather than encapsulating this with OH-specific parameters).
On another note, landscape mode is currently not well designed (too large paddings/safe areas).

11. Too many abstraction layers creating complexity
Editing in an abstraction layer (OH-specific yaml) (which gets stored as JSON internally) of an abstraction layer (oh-specific widget structure) of an abstraction layer (vue components) of an abstraction layer (F7 components) that creates HTML/CSS/JS does not “feel” right. At least you can see the limitiations and flaws that get introduced with each additional layer when working with pages and widgets.

Final thoughts:
As I stated in the beginning, I am not a developer myself, so I can’t make proper suggestions for solutions. But wouldn’t it be possible to use a more standard-oriented approach in the sense that

• Pages and (even more important) Custom widgets are created using “vanilla” Vue/F7 components (for which already a good documentation is available)
• Keep all customization options from the underlying Vue/F7 frameworks (at least design options like app.css) available and unchanged
• OH core provides a method for data-binding the vanilla components (similar to the “props” approach)
• OH comes with predefined Widget templates, which can be used as-is by entry-level users, but also be changed by advanced users

[Julian_Divett]

My first few days of playing with the interface has been quite tough too but I do see that it will allow for a much improved UI over Basic or even Habpanel. Of course we have to remember this is a community project so I never expect to have an early release to be everything we would want.

I agree that documentation will be a great start as well as more prebuilt widgets.
The coding interface is unfortunately for me the big issue.
I hope there will be or is a way to use an external editor. Trying to maintain mutliple pages though the gui is not realistic for me. May be just to get something up quick. But going backwards and forwards between the editor and running pages is painfully slow.

[rlkoshak (Rich Koshak)]

@c_r

Rather than developing new UI features I think we should prioritize creating a proper documentation thats suits a major release like OH3.

You say “we” so does that mean you are volunteering to help? We sure could use the help.

I personally am working on completing the Getting Started Tutorial though am struggling a bit with Pages. Yannick is working on comprehensive docs for all the details. Jerome is also work on docs (If I missed anyone it was not a deliberate slight, I’m way behind on following the github issues). But that’s only three people who each have full time jobs and contribute a significant amount of time to OH doing other things.

And since all contributions are voluntary, the only thing one can realistically prioritize is their own time and their own contributions. No one can make anyone else work on something they don’t want to.

@c_r

Even more important: there is no way of code-versioning for pages and widgets. No rollback whatsoever possible (except for JSONDB file backup). In OH, I simply use git to version-control all my sitemap, thing, items etc.

You can also git control the JSONDB (I do this myself). It works surprisingly well.

[c_r]

Hi, thanks for your feedback. I am not complaining about the fact that not everything is perfect yet. That’s of course absolutely normal and acceptable for a new OSS major release. I know that it is down to a very few people working particularly on the UI and, as I mentioned already, appreciate their work a lot (incl. your work in the forum ).

As with my previous posts I try to help where I reasonably can. As for the documentation, I don’t feel to be in a position yet to do that. Substantial knowledge is needed about what’s going on behind the scenes (Standard widgets, nesting, integration of Vue/F7 just to name a few), and I don’t want to spent my time on “reverse engineering” source code to understand what’s going on to be honest.

I was hoping to get some more thoughts on the more fundamental issues (like 1., 2., 5., 7. 11.), and the “final thoughts” section. It’s totally OK if the UI OH outputs is not perfect out of the box, but then I would like to be able to fix that with a bit of configuration using built-in tools or simply changing a few config files (e.g. CSS) and not run into some fundamental/general (built-in) limitations.

[rlkoshak (Rich Koshak)]

I can’t address the rest (except for 7 which I kind of already did, what specific issue do you have with using git and JSONDB at this time?). I’m not a developer on OH.

[boconnor (Brad O'Connor)]

I’d agree very strongly with the need for better documentation (and also understand that it requires someone to volunteer their time). I have made the move to OH3 and can see just how powerful and impressive it is.

I have been trying to build a new UI for my house, and have achieved something basic, but have struggled to build the UI that I have imagined. Until there is much more complete documentation, I feel like the barrier to entry is too high for most people. I would love to contribute but firstly I don’t have the spare time (maybe in 5 years or so…), and secondly I don’t understand the material well enough to write documentation for it (chicken vs egg problem).

[rlkoshak (Rich Koshak)]

@boconnor

secondly I don’t understand the material well enough to write documentation for it (chicken vs egg problem).

No one can argue about a lack of time. We all have to manage what time we have in what ways we want to.

But I do want to address this last part.

You do not have to be an expert (right now) to contribute to the docs. You don’t have to already be an expert to decide you want to contribute to the docs. You just have to be willing to dig in and become an expert, taking notes as you go. Those notes will become your docs.

Do you think I was an expert on Pages before I started writing Building Pages in the OH 3 UI - Introduction? No, I still wouldn’t call myself an expert on Pages. But I came up with a series of “how do I do X?” questions, answered each one in turn, sometimes with help from the developers, other times finding bugs, and still other times getting help from the community. Then strung them together into a narrative and bam, I’ve a tutorial.

Reference docs are very much the same only a little more tedious as you have to cover each and every little detail. But it’s the same overall approach. Pick something and dig into it, take notes and turn those notes into a reference guide.

If we wait for everyone to become an expert before they ever decide to contribute to the docs, the only ones who will be writing docs are the developers, and as is infamous in the industry, developers don’t like to write docs. And they are not the best ones to do so often as they have a lot of unacknowledged assumptions and base knowledge which will cause them to skip important parts.

So really, there is no chicken and egg problem. The egg comes first. You have to decide to become an expert in something and the best time to write the docs is as you are becoming that expert. That way you don’t lose what it was like to start from the beginning.

So anyone can write docs. And they can choose to do so at any time. But writing docs is not just putting words on a webpage. It also involves all that work you have to put in to learn something well enough to write the docs in the first place.

[hubsif (Hubsi)]

@c_r I’ve had a similar experience as you had: The Virtual Meetup was quite impressive and made me start playing around with OH3 immediately. After a quick glance at the many new cool features, I wanted to check out the new design and started creating a new layout for my tablet. I then got stuck soon, since it wasn’t possible to nest rows and columns. Also, I wanted to show a clock at the corner and had to find out that it wasn’t possible to add any Javascript. That made me understand why HABPanel was still present - but I wanted the new cool design instead :-).
I also tried to create my first custom widgets. At the time there was no documentation for that available at all, so I rummaged the forums and when that didn’t lead to results, I began looking at the source code.

All that lowered my enthusiasm, but I still see the great potential OH3 and it’s new UI has! I also set great store on user experience and I think the most successful apps are those that are easy to use and intuitive, yet extensive and flexible. Somehow I wanted to help OH3 become a great success, so started looking into how the things I desire could be realized, got acquainted with Vue and F7 and started contributing.

I then realized once more again how big a software like OpenHAB actually is! There are so many use cases and every smart home user wants to have different features. I also learned how much time it costs to get even small ui adjustments/fixes done, e.g. many of them have to be tested on different devices and screens. With my time being limited, I found out that I can’t contribute a fraction of what I thought I could - with so much more improvement ideas in my mind!

With all this in mind I think the OH team has done an amazing job! I can’t imagine how much effort it must have cost to get OH3 to what is is now!

This said, I actually started replying because I wanted to comment on a few of your thoughts - from my personal point of view:

1. Blackbox Predefined widgets limit possibilities:

Well, I think that predefined widgets are actually required to get a good ux, since without them an unexperienced user would have to learn about how to create widgets, instead of quickly layouting his first page. You speak of missing templates later on. These predefined widgets are IMHO some kind of “template”.

I think the great flexibility of mainUI, i.e. the ability to create custom widgets, actually creates a false delusion here: With most smarthome applications you only have predefined widgets and the feature of huge customization in OH3 makes one want even more .

2. “Hardcoded” Styles
3. Inline Styles everywhere

Like mentioned above, I also wanted to add some Javascript to a widget. Same for CSS and I think I’ve seen some forum posts about other people wanting to add CSS to a page, e.g. for backgrounds.
It would also help creating cleaner widgets, as general (widget wide) CSS rules could be defined and wouldn’t have to be repeated for each component.
I guess that will be coming soon. It’s also on my list of improvements to contribute, but it’s not trivial and regarding JS security concerns have been raised.

4. No documentation available

Well, documentation, the pain for every developer. Considering this, the docs are actually very good, I think!

6. No editing of pages and widgets outside OH Admin UI

Hm, I’d like to understand that feature request better: An external editor would of course not be able to show a preview. And clearly you can write YAML anywhere and just paste it into the app’s editor.
Can you please explain more detailed how you’d like this to work?

9. No Demo/Template UI

I agree that this could be very helpful, as I’m one of those learning fastest from examples. It’s part of what I expect from good UIs, together with a lot of “hinting”. This certainly can still be improved.

11. Too many abstraction layers creating complexity

I can’t actually fully agree to this, JSON for example is not really accessible to users. And using those frameworks actually simplifies things, I think, as it enables consistent designs and scripting. What I think would be helpful, though, is a “documentation extract” of the basic (f7) components and their parameters.

Pages and (even more important) Custom widgets are created using “vanilla” Vue/F7 components

Actually, oh-widgets just extend vanilla f7-components so you can edit them more easily and e.g. select an item as label. I don’t see how that’s unfavorable.
Right now you can just add e.g. a rollershutter widget, set an item for it and you’re done. With vanilla f7 you’d have to create columns, icon buttons, … and then somehow get each connected to an item command. Do you really prefer that?

As others already mentioned, I think most of what's lacking is just due to lack of time of the developers - and now with OH3 released they're probably snowed under with a lot of bug fixes from the many people wanting to use it :smiley: .