[Main UI] Add Setup Wizard

[ghys]

This launches a setup wizard when openHAB is started for the first time. It allows to:

• set some regional settings (language, region, timezone)
• set the location, optionally with the help of the browser Location API
• install an initial set of add-ons

It is also possible to skip any of these steps, or the setup wizard altogether. Regardless, the "overview" layout page will be created so that it can act as a detection mechanism to determine whether the setup wizard has already run or not, and prevent it from being shown a second time. Therefore, deleting the overview page has been made impossible in the UI's pages list.

Here's how a completely fresh openHAB instance looks like with this PR when accessing the UI for the first time (note how the user is immediately asked to sign in i.e. create their account, and that the HABot text box/astro inbox entries immediately appear in the chosen language):

When we localize the UI properly we'll try to make the language change as soon as the setting is selected on the first screen.

I encourage everyone to do exploratory testing of this one, and comment on the design/wording of messages, as it's the first time experience new users will have and therefore I think it's important that we get it right IMO.

Signed-off-by: Yannick Schaus github@schaus.net

[kaikreuzer]

Wow, that looks awesome! Great stuff and a huge step forward in first-time setup UX. 👍

A first question I'd have: Would it be possible to derive the language/region/timezone from the browser, so that those fields are prefilled? It feels a bit tedious for the user to fill in all 3 values from long selection lists, although it is very often just a fixed triplet (many countries simply have just one language and one timezone).

[ghys]

A first question I'd have: Would it be possible to derive the language/region/timezone from the browser, so that those fields are prefilled? It feels a bit tedious for the user to fill in all 3 values from long selection lists, although it is very often just a fixed triplet (many countries simply have just one language and one timezone).

Modern browsers have Intl.DateTimeFormat().resolvedOptions(), this is what I get on 2 different browsers:

So I believe we could parse the language & region from the locale, if we're careful, and also the timezone if we make sure there's a match in the parameter options.

[yveshanoulle]

I think it's a huge improvement for real first users. Much appreciated. The better a community support it's first time users, the faster and better it grows.

Please don't forget that a lot of people do set up a new instance, that are not first time users. I have my openhab hardware double. When I want to install a new version: I start with a new installation of the new version. (From scratch, like I am a person new to the software) I do an initial launch, just to see of openhab launches. And then I download my configuration from my source control system. When that works, I turn the other instance of openhab (they both have a different IP adres)

From that moment on, I do all my changes from my own computer upload it them to the sourcecontrol system download them on the hardware (preferable by clicking a button in the openhab app)

This is not a first user experience, so I don't want you to do anything for my experience, yet I hope you also don't break that.

[ghys]

This is not a first user experience, so I don't want you to do anything for my experience, yet I hope you also don't break that.

Don't worry, I'm rather on the careful side when it comes to breaking stuff, I tend to avoid it when possible. 😎

The setup wizard will not get in your way in the scenario you describe, because if the "marker" indicating that it has already run (the overview page has been created - btw happy to discuss something else but it was the best I could come up with), it will not run again; and in a restore-from-backup scenario it's likely you include the JSON DB - including the overview page stored from a previous run.

If it does run, for instance you migrate from OH2 which doesn't have this overview page concept, all it does for now is help you (re)configure some regional settings and install the add-ons you specify, so it's hardly destructive, and as described above you can skip it entirely or any step of it.

I believe we could parse the language & region from the locale, if we're careful, and also the timezone if we make sure there's a match in the parameter options.

Implemented in https://github.com/openhab/openhab-webui/pull/306/commits/cdf0cd70c4b0dde1e9240f81a6fa5d2d30d18552

[yveshanoulle]

The setup wizard will not get in your way in the scenario you describe, because if the "marker" indicating that it has already run Well before I download the configuration, I do go to openhab page, just to see if it runs. At that moment I haven't downloaded anything, so I assume your wizard comes up then I go to a terminal to download the code from sourcecontrol

I'm not using the "restore-from-backup scenario", hence also not backup restore teh json. I'm using the configuration files (not sure that is the right name) where I have defined services, items, things, servicemap

[ghys]

Nothing to add for now, so I consider this PR ready 🚀

[hmerk]

Again, excellent work Yannick !!!!!

[wborn]

It looks super nice and helpful! :+1: :1st_place_medal:

What would be nice additions:

• case insensitive sorting for add-ons
• dark mode :sunglasses:

[gersilex]

What about asking for the location first and then derive the time zone, region and language from that?

Also the call to action at the end [Finish] is too subtile in my opinion and might be in the primary color and also say something more enthusiastic like [Get Started] or something. It is true that the initial configuration has finished, but that' where I as a user get started and have fun in openHAB.

In any case, amazing work once again!

[ghys]

What about asking for the location first and then derive the time zone, region and language from that?

that's not trivial, but since the locale & timezone is detected now (https://github.com/openhab/openhab-webui/commit/cdf0cd70c4b0dde1e9240f81a6fa5d2d30d18552) it's kind of a moot point.

say something more enthusiastic like [Get Started] or something. It is true that the initial configuration has finished, but that' where I as a user get started and have fun in openHAB.

had the same thoughts exactly, the screenshot in the OP is outdated 😄 (see https://github.com/openhab/openhab-webui/pull/306/commits/a272427c728c7720c7da25b1d86230da8ef3a251)

case insensitive sorting for add-ons

that's the order of the API, so not sure where it should be fixed in the client or the backend 🤔

dark mode

already there if your OS tells your browser to use dark mode - I'd tend to think it's enough, no need for a switch, it's per device anyway.

[ghys]

Please deal with me as I self-merge my own PR again, but with a bit of an explanation/disclaimer this time about why I'm giving myself that right:

• I feel those are not going to be properly tested/reviewed anyway, since there might be a reluctance from other active maintainers to get involved in frontend technologies they are not familiar with (if there's people reading this who are, please step up, we need you!);
• Maybe the best way to figure out whether there are problems with these additions is to let Jenkins build distributions including them, and let interested parties test them - this is IMHO probably acceptable while openHAB 3 snapshots are still not deemed ready for prime time yet, so there's leeway in what's included in them without proper review - experiments and beta features might be considered valuable to include for the sake of having more people test them; of course when there's an established userbase of those snapshots, potentially breaking changes are not going to be acceptable, so this policy will have to be revisited;
• People testing OH3 snapshots at this time cannot be guaranteed there isn't going to be a critical bug in them; however, those which are properly reported are probably going to be fixed in a timely fashion in a subsequent snapshot as we keep the momentum going, because that's where the focus is;
• We are still in a period where adjustments can easily be made to these features after some testing, i.e. the feature set doesn't have to be final for PRs like these to be merged, it could be done in an "organic" fashion: merge early, test, and figure out what's missing.

If there's any disagreement with the above, please let me know and I will stop the self-merging. 😊

[gersilex]

Thank you for the details about why this has been merged by yourself. Although I'm no active/regular maintainer, I understand the code I found in the diff and don't see any problems with that.

If you are looking for someone that is deeply in the vue and f7 space, I can not help you, but if you are looking for someone to challenge your changes I am really open to that in a productive and friendly manner.

If interested, what about testing. I see some interesting and important steps for first-time users. Are there any plans for automated end-to-end testing so we can ensure that it won't break when this or other parts of the openHAB codes change?

[ghys]

If interested, what about testing. I see some interesting and important steps for first-time users. Are there any plans for automated end-to-end testing so we can ensure that it won't break when this or other parts of the openHAB codes change?

Yes, good remark; I put the infrastructure in place early on to do both unit tests with Jest and e2e tests with Cypress, but writing them takes a lot of time, so it didn't get a lot of love... the main focus being adding features to make the whole thing usable.

That being said I believe feature-wise the UI is in good shape, and slowly getting there, so there will probably be fewer of these big feature additions and more PRs focused on stablization/behind-the-scenes improvements; there's a lot to be done in that area, but a lot of feedback will likely come when there's a formal go-ahead to the community to start trying out OH3.

[gersilex]

Sounds good. I already worked with Cypress and feel like I can support you there with a couple of realistic test cases. I also work closely with quality engineers that can help us do the end-to-end tests in an efficient and correct (quality-wise) manner.

You sound like you have a strong vision in mind for the cypress structure or it already is done and I could not find it. Feel free to ping me as soon as you need someone develop and write e2e test cases. I'm happy to help with that.

[ghys]

You sound like you have a strong vision in mind for the cypress structure or it already is done and I could not find it. Feel free to ping me as soon as you need someone develop and write e2e test cases. I'm happy to help with that.

Excellent! To be honest there's no grand plan on these tests, I just made sure we could have some at some point, How they work is briefly mentioned in CONTRIBUTING.md - you should be able to run them with npm run test:e2e or npm run test:e2e:gui. As stated below in this file you should also launch npm start in parallel beforehand and make sure it runs on http://localhost:8081 (or adjust cypress.json as necessary).

The Cypress structure is in www/test/cypress (here) and there's a first basic test here, but there's not much else.

[gersilex]

Awesome, this should be enough to get me started. I'll think about useful, realistic and correct test-cases and will create a new Issue for those before working on them to keep everyone who wants to contribute involved and informed.

Thanks for all the information!

[kaikreuzer]

Please deal with me as I self-merge my own PR again

@ghys As always, absolutely fine and no need to justify this lengthy! Sorry that I wasn't available the last days and hence didn't merge - but as you say, I'd anyhow not be able to do a proper review of it.

if you are looking for someone to challenge your changes I am really open to that in a productive and friendly manner.

@gersilex This is exactly the sort of people an open source project is longing for! And everybody is very welcome to review/test/comment on any PR, this should not just be the maintainers. And doing so is anyhow the only way of becoming a maintainer one day :-) Awesome to hear that you have Cypress experience and want to help on that front!

[wborn]

One thing I just noticed is that it is not obvious to see in the wizard which add-ons are already installed by the standard package. So users might be scratching their heads how to install rrd4j. Some users might not want to use basic/habpanel/rrd4j so it would be easier for them if they weren't preinstalled initially. Will there also be a UI to install the demo package instead of the standard package?

[kaikreuzer]

@wborn I consider the packages to be outdated and would not want to expose them to users at all anymore. I only kept the demo package for us to easily set up the demo server and maybe for other purposes - but that should imho not be supported through the setup wizard. "standard" should really be the standard installation that everybody has, who sets up openHAB the normal way - i.e. through the wizard. I'd be fine to remove basic/habpanel/rrd4j from the karaf feature, if the setup wizard deals with that. With the new UI, I'd think that Basic UI and HABPanel are indeed really optional UIs that aren't mandatory to have. Wrt rrd4j, we rely on having some persistence present, so the setup wizard might urge to install rrd4j unless the user votes for some other persistence service. Wdyt?

[wborn]

Yes I think it would be best to remove those add-ons from the standard package. I think the demo package may have been used by quite a few OH2 users for evaluating OH and as basis for their own configurations sitemaps/items/rules files. At least that's how I used it when starting with OH years ago. :wink: Is something else planned to showcase openHAB on your own machine and decrease the learning curve by providing a fully fledged working example?

[kaikreuzer]

My suggestion is to simply be able to have the demo package by editing the addons.cfg file. The demo was never good as a starting point, because you couldn't evolve the demo setup to become your own personal one, since it wasn't really possible to switch the selected package afterwards. I personally would actually tend towards a setup as we had it with openHAB 1: Simply have a zip file with example content that you can extract to your conf folder and where you clearly see what is going on.

[wborn]

example content that you can extract to your conf folder

That makes sense and that's also how I currently use my own version of the demo content for testing OH3.

[digitaldan]

Sorry i am very late to this party! Nice work @ghys ! Looks awesome, can't wait to test it out.

[ghys]

As always, absolutely fine and no need to justify this lengthy! Sorry that I wasn't available the last days and hence didn't merge - but as you say, I'd anyhow not be able to do a proper review of it.

No worries at all, just wanted to set the record straight on why I'm kind of bypassing the general 4-eyes rules in place in other repos; it's mainly because while we're in "heavy construction mode" and adding features, I tend to prefer working on the next thing on my list from a clean slate i.e. branching from the latest master with the previous changes already merged - to avoid potential conflicts and to have the rather good feeling of being cutting-edge, testing everything at once in the field.

I'd be fine to remove basic/habpanel/rrd4j from the karaf feature, if the setup wizard deals with that. With the new UI, I'd think that Basic UI and HABPanel are indeed really optional UIs that aren't mandatory to have. Wrt rrd4j, we rely on having some persistence present, so the setup wizard might urge to install rrd4j unless the user votes for some other persistence service. Wdyt?

I kind of liked that they were preinstalled so that "clueless" new users (no disrespect, of course) could discover them as part of the standard features they're likely to want. So I'd be fine to keep them in a standard package as power users can always uninstall them afterwards if they don't need them; that said, alternatively, I've been thinking about adding "Recommended" buttons or similar to the "Install Add-ons" part of the setup wizard so that people can add popular, non-hardware dependent add-ons quickly before they choose those specific to their case i.e. bindings.

[kaikreuzer]

I've been thinking about adding "Recommended" buttons

Yeah, that was my idea to move this to the setup wizard. It could have a page of "suggested" add-ons, ideally already preselected, if a noob user comes along and wants to try openHAB out. The experienced user can easily then deselect stuff, he does not want (or skip the setup wizard altogether).