Add intergrated Help Features #2088

JustinGeorgi · 2023-09-24T00:52:31Z

Closes #2058.

This converts the developer sidebar into a multipurpose dock.
It keeps the previous developer sidebar as the Tools panel and adds a Help panel.

The new Help panel contains 4 different sections:

A context dependent section that will show basic help for the administrative page currently viewed. These pages give basic definitions, some simple tips and links to the relevant full documentation.
An add-on section that lists all the currently installed add-ons and provides direct links to their documentation pages.
A FAQ section for simple answers to common questions with internal links to help guide the users, some external links to relevant resources, and links to documentation pages providing more details about the question.
A Quick-Start section that guides a new user with click-by-click instructions for everything from binding installation to adding a widget to a MainUI page with links to the detailed Getting Started Tutorial for each step. This section is opened by default when an administrator opens a new MainUI instance with no configured overview page (i.e., most likely a new user).

All of the main setting list pages and the overview page now have a help icon in the navbar that toggles the help dock.

FAQ and Quick-Start data are stored in separate JSON formatted files for ease of addition and maintenance.

Signed-off-by: Justin Georgi justin.georgi@gmail.com

florian-h05 · 2023-09-26T14:51:57Z

Can you please rebase your PR? Your commit history is messed up because of the merge ...

JustinGeorgi · 2023-09-26T15:32:15Z

Can you please rebase your PR? Your commit history is messed up because of the merge ...

I'll give it a try when I get a chance later. As far as I know, it's messed up partially because I'm still learning all this rebase stuff and somehow messed it up the first time.

Edit: Did I figure it out? It looks like I figured it out.

relativeci · 2023-09-27T00:56:31Z

Job #1257: Bundle Size — 15.8MiB (+0.26%).

380151f(current) vs b7270d2 main#1158(baseline)

Important

Bundle introduced 1 and removed 1 duplicate package – View changed duplicate packages

Warning

Bundle introduced 13 new packages: @jsep-plugin/regex, @jsep-plugin/arrow, @jsep-plugin/object and 10 more – View changed packages

Bundle metrics

10 changes

5 regressions

1 improvement

	Current Job #1257	Baseline Job #1158
Initial JS	`1.89MiB`(`+13.11%`)	`1.67MiB`
Initial CSS	`609.63KiB`(`+0.12%`)	`608.89KiB`
Cache Invalidation	`93.81%`	`93.95%`
Chunks	`217`(`-0.91%`)	`219`
Assets	`683`(`-0.87%`)	`689`
Modules	`3027`(`+78.06%`)	`1700`
Duplicate Modules	`173`(`+92.22%`)	`90`
Duplicate Code	`1.61%`(`-17.44%`)	`1.95%`
Packages	`152`(`+10.14%`)	`138`
Duplicate Packages	`16`(`+6.67%`)	`15`

Bundle size by type

3 changes

3 regressions

	Current Job #1257	Baseline Job #1158
JS	`9.28MiB` (`+0.27%`)	`9.25MiB`
Other	`4.74MiB` (`+0.3%`)	`4.73MiB`
CSS	`860.87KiB` (`+0.16%`)	`859.49KiB`
Fonts	`526.1KiB`	`526.1KiB`
Media	`295.6KiB`	`295.6KiB`
IMG	`140.74KiB`	`140.74KiB`
HTML	`1.23KiB`	`1.23KiB`

View job #1257 report View JustinGeorgi:jag-help-doc branch activity

ghys

Thanks for this @JustinGeorgi!
I will test it asap, one initial remark though:

ghys · 2023-09-30T20:10:31Z

bundles/org.openhab.ui/web/src/pages/settings/pages/pages-list.vue

+        <f7-link v-if="$store.state.developerDock" icon-f7="question_circle_fill" @click="$f7.emit('toggleDeveloperDock')" />
+        <f7-link v-else icon-f7="question_circle" @click="$f7.emit('selectDeveloperDock',{'dock':'help','helpTab':'current'})" />


How about when the developer dock can't be displayed because the screen is too narrow?
This new button/link will still be displayed but appear to (and in fact will) do nothing I think, which is not good.
Maybe best remove them when the current screen is not able to display the dock - or keep them but just link them to relevant documentation instead.

Oh yeah, forgot that point from the previous discussion. If it's all the same to you, I'm inclined to just remove it so it doesn't clutter the navbar on narrower screens.

I do think it's best to either remove it, or perhaps change it to a regular link to the documentation when the developer dock wouldn't fit.

By the way, I think when those icons make their way in the navbar, we should replace these buttons in the empty state placeholders:

You have a message saying "add your first thing manually with the button below" but the actual button below opens the documentation. It was an oversight which should be corrected.

By the way, I think when those icons make their way in the navbar, we should replace these buttons in the empty state placeholders:

I hadn't thought of that, that's a good point.

You have a message saying "add your first thing manually with the button below" but the actual button below opens the documentation. It was an oversight which should be corrected.

Do you mean this?

The button is link to the docs, but the "click here" refers to the list item itself. Maybe that's not clear enough...

Otherwise, I'm not sure which button you're referring to.

By the way, I think when those icons make their way in the navbar, we should replace these buttons in the empty state placeholders:

Since we decided to just remove the button on narrow screens, I only removed the documentation buttons after the placeholders when the navbar help buttons are visible. So, on narrow screens instead of the navbar button you will still see the documentation buttons.

You have a message saying "add your first thing manually with the button below" but the actual button below opens the documentation. It was an oversight which should be corrected.

Do you mean this?

I'm still not 100% sure which message you are referring to, but I've added arrow indicators to all the click here list items in the quickstart section which I hope will make it more clear that those specific items are clickable.

florian-h05 · 2023-11-17T20:16:40Z

Hi @JustinGeorgi, since it seems that @ghys is busy at the moment, I will take over the review of your PR, so stay tuned.

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Signed-off-by: Justin Georgi <justin.georgi@gmail.com>

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

florian-h05

LGTM, thanks! Great addition.

I have rebased your PR, and I decided to directly commit my findings during review (this saves us both work, I anyway need to test some of my requested changes before giving a suggestion, then I'd have to wait for you implementing it, and finally test it again).

What I changed:

You used window.innerWidth for the breakpoints. This works, but does not update when the window is resized. Better to use $f7.width, because this is dynamic.
Added back a few documentationLinks that were removed, but still needed.
Improved styling of the "Page Help" feature: The list items now look the same as for all other tabs.
Added a cloud connector link to the remote access FAQ entry.
Added a link to Thing add to the Quick Start entry.

In case one has suggestion regarding the content, let's merge this and then open a new PR. This PR is already big enough, no need to make it even bigger ;-)

JustinGeorgi · 2023-11-18T00:24:04Z

I decided to directly commit my findings during review

No worries, I think that's a fine idea.

Thanks for the review!

Follow-up for openhab#2088. I forgot that during review, let's do it now. Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

Follow-up for #2088. I forgot that during review, let's do it now. Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

) Follow-up for #2088. Depends on openhab/openhab-docs#2199. Also add the help sidebar button to the settings and list pages where it is missing. --------- Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

JustinGeorgi requested a review from a team as a code owner September 24, 2023 00:52

JustinGeorgi force-pushed the jag-help-doc branch from ba85432 to 75bff32 Compare September 24, 2023 04:09

JustinGeorgi force-pushed the jag-help-doc branch from 529e81c to e047d39 Compare September 27, 2023 00:51

JustinGeorgi force-pushed the jag-help-doc branch from e047d39 to 6c80f13 Compare September 27, 2023 01:00

ghys reviewed Sep 30, 2023

View reviewed changes

florian-h05 added enhancement New feature or request main ui Main UI labels Oct 3, 2023

JustinGeorgi force-pushed the jag-help-doc branch from 6c80f13 to 6d5b0eb Compare October 14, 2023 04:30

JustinGeorgi force-pushed the jag-help-doc branch from 0d0f283 to c791f31 Compare October 23, 2023 14:04

JustinGeorgi added 14 commits November 17, 2023 21:18

Resize col test

c2b579e

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Working Resize Grid

0646707

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Functional test version

139cbee

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Add context dependent pages

abd429b

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Move dock selection to app

9e3d615

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Add help button to navbars

43fce84

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Set quick start to auto open on new installs

2d44208

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Update FAQs

ba57319

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Fix FAQ errors

1bd7265

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Fix build errors

a223f09

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Fix build errors

33f4ded

Signed-off-by: jgeorgi <justin.georgi@gmail.com>

Fix help link on narrow screens

74a0e5d

Signed-off-by: Justin Georgi <justin.georgi@gmail.com>

Fix conflict error

aec2fe1

Signed-off-by: Justin Georgi <justin.georgi@gmail.com>

Link and button updates

8e8bab4

Signed-off-by: Justin Georgi <justin.georgi@gmail.com>

florian-h05 force-pushed the jag-help-doc branch from c791f31 to 8e8bab4 Compare November 17, 2023 20:34

florian-h05 added 2 commits November 17, 2023 21:43

Review changes to /settings/ pages

132e668

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

Review changes to remaining existing pages

fbf6eb9

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

florian-h05 added 3 commits November 17, 2023 21:56

Minor clean-Ups for app.vue

2ee8e45

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

Improve styling of "Page Help"

a303c86

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

Add cloud connector links to FAQ & Add Thing link to Quick Start

380151f

Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

florian-h05 approved these changes Nov 17, 2023

View reviewed changes

florian-h05 added this to the 4.1 milestone Nov 17, 2023

florian-h05 merged commit b4128cb into openhab:main Nov 17, 2023
6 checks passed

florian-h05 changed the title ~~Intergrated Help Features~~ Add intergrated Help Features Nov 17, 2023

JustinGeorgi deleted the jag-help-doc branch November 18, 2023 00:54

florian-h05 added a commit to florian-h05/openhab-webui that referenced this pull request Nov 19, 2023

Move JSON defs for help features to assets

3c5810e

Follow-up for openhab#2088. I forgot that during review, let's do it now. Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

florian-h05 mentioned this pull request Nov 19, 2023

Move JSON defs for help features to assets #2178

Merged

florian-h05 added a commit that referenced this pull request Nov 19, 2023

Move JSON defs for help features to assets (#2178)

f053166

Follow-up for #2088. I forgot that during review, let's do it now. Signed-off-by: Florian Hotze <florianh_dev@icloud.com>

florian-h05 mentioned this pull request Jan 17, 2024

Update descriptions in the settings menu #2273

Merged

florian-h05 mentioned this pull request Jan 27, 2024

Help sidebar: Move docs to docs repo & Integrate them into the UI #2253

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add intergrated Help Features #2088

Add intergrated Help Features #2088

JustinGeorgi commented Sep 24, 2023 •

edited by florian-h05

Loading

florian-h05 commented Sep 26, 2023

JustinGeorgi commented Sep 26, 2023 •

edited

Loading

relativeci bot commented Sep 27, 2023 •

edited

Loading

ghys left a comment

ghys Sep 30, 2023

JustinGeorgi Sep 30, 2023

ghys Oct 9, 2023

JustinGeorgi Oct 10, 2023

JustinGeorgi Oct 14, 2023

florian-h05 commented Nov 17, 2023

florian-h05 left a comment •

edited

Loading

JustinGeorgi commented Nov 18, 2023

		<f7-link v-if="$store.state.developerDock" icon-f7="question_circle_fill" @click="$f7.emit('toggleDeveloperDock')" />
		<f7-link v-else icon-f7="question_circle" @click="$f7.emit('selectDeveloperDock',{'dock':'help','helpTab':'current'})" />

Add intergrated Help Features #2088

Add intergrated Help Features #2088

Conversation

JustinGeorgi commented Sep 24, 2023 • edited by florian-h05 Loading

florian-h05 commented Sep 26, 2023

JustinGeorgi commented Sep 26, 2023 • edited Loading

relativeci bot commented Sep 27, 2023 • edited Loading

Job #1257: Bundle Size — 15.8MiB (+0.26%).

ghys left a comment

Choose a reason for hiding this comment

ghys Sep 30, 2023

Choose a reason for hiding this comment

JustinGeorgi Sep 30, 2023

Choose a reason for hiding this comment

ghys Oct 9, 2023

Choose a reason for hiding this comment

JustinGeorgi Oct 10, 2023

Choose a reason for hiding this comment

JustinGeorgi Oct 14, 2023

Choose a reason for hiding this comment

florian-h05 commented Nov 17, 2023

florian-h05 left a comment • edited Loading

Choose a reason for hiding this comment

JustinGeorgi commented Nov 18, 2023

JustinGeorgi commented Sep 24, 2023 •

edited by florian-h05

Loading

JustinGeorgi commented Sep 26, 2023 •

edited

Loading

relativeci bot commented Sep 27, 2023 •

edited

Loading

florian-h05 left a comment •

edited

Loading