Replace help popup with in-page text

[dreadnaut]

Originally reported on Google Code with ID 176

The current popup help solution is... dirty, works only with javascript enabled, creates
a new window, etc.

The patch below (against r333) replaces the external popup with a modal layer with
the help text (included as an iframe, to minimize changes), but also restores normal
urls, so the help text can opened in a new tab/window if javascript is not enabled,
or the user decides to.

Reported by dreadnaut on 2013-02-11 18:39:18

<hr> * Attachment: nopopup-r333.diff

[Christopher Kramer]

Hmm. Okay, I don't really see a real need for change here, but we can change things.
But please not only because modal-windows are cool and modern, but because it really
improves things.

+ I like the fact that it works without JS (which would be easy with the popup-approach
as well).
+ Looks cool, modern and clean.
- I consider a modal iframe-based "window" more dirty than a normal popup, but that
might be personal. But I don't see a reason why the popup-window is "dirty".
- What's wrong with creating a new window, if it makes sense from a usability point-of-view?
So we need to compare usability.
And I think it lacks usability compared to the popup-approach because

1. There is no intuitive close-button. Of course most users know they can click somewhere
to close it, but some might not. And even users that know might need to think 5 seconds
more to realise how they can close it (after searching for the close-button). Additionally,
it is impossible to close it, if your screen/window is as small or smaller as the "modal
window". This is more a theoretical issue, but might be a problem for some mobile devices.
So I'd definitely add a close-button.
2. Impossible to see the application clearly while the help-text is displayed. This
means you cannot read the text and have a look at the available UI without closing
and opening the modal-window. This is due to:
2a. Impossible to move modal-windows on another screen. I like to move help-windows
on one screen and the application described on the other one. Completely impossible
with modal-windows.
2b. Not possible to move the modal-window (which would require a drag&drop handler).
Can be implemented (lots of libraries there), but would require a bunch of unnecessary
JS code.
2c. the background is not clearly readable because of the overlay.


So what positive arguments do you see for the modal-window from a usability point of
view?

Reported by crazy4chrissi on 2013-02-12 17:40:03 - Labels added: Type-Enhancement - Labels removed: Type-Defect

[dreadnaut]

There are number of issues with the current system:

* requires javascript: this is easy to solve, replacing javascript:void() with the
correct link as in the patch;

* pop-up based: subject to browser mood and pop-up blockers configuration; it will
open a new tab anyway on mobile browsers (including tablets) and full screen/full browser
OSs: therefore we will suffer 2/2a/2b for a growing numbers of users;

* fixed size to accomodate for the "show all documentation, scroll on current" system,
might be tiny or unreadable depending on DPI, font size;

* we cannot store proper documentation since it ends up inside the code: these are
just tooltips, and they should work as such.

Seeing this, it is my opinion that pop-ups should be avoided, and probably help text
should be reduced to tooltips, with proper documentation as an external source.

A modal layer is just one approach, and I'd be happy to replace it with something better.
Maybe a proper non-modal tooltip, or a thin box at the bottom or on the right-hand
side of the page (good for 2b,2c, and similar to 2a) —the latter would actually be
my favorite solution.

The current iframe on layer is just what can be done easily with the existing fixed
size system. An iframe is also not worse than a popup: still one request, less complex
than XHRs or handling the help text with javascript.

Reported by dreadnaut on 2013-02-12 18:23:03

[Christopher Kramer]

Okay. I agree using tooltips would be a real improvement. And proper documentation in
a wiki.

I'd love non-modal tooltips. The first thing google gave me:
http://www.walterzorn.de/en/tooltip/tooltip_e.htm
Looks pretty much like what I had in mind when I read your answer.

But I think we should not bundle 40 KB of JS-Code for this. Maybe we could use some
Google-CDN-Hosted library like jQueryUI:
http://jqueryui.com/tooltip/
https://developers.google.com/speed/libraries/devguide
Looks good as well in my opinion.

What do you think?

Reported by crazy4chrissi on 2013-02-12 18:45:46 - Status changed: Accepted

[dreadnaut]

We can have pure css tooltips, no javascript required :)

There is however one problem with tooltips: the on-hover interaction makes for immediate
feedback. Tooltips that take time to load are already too slow for a good UX. This
means that text cannot be loaded lazily, but should be ready and therefore inside the
page. And this means heavier pages.

This is why I would prefer a proper panel appearing on click, as I was saying, either
on the side or at the bottom of the page. See attachment for a rough idea.

Reported by dreadnaut on 2013-02-12 19:21:08

<hr> * Attachment: bottom-panel.png<br>

[Christopher Kramer]

Right, pure css tooltips would probably be better for a compact tool like phpLiteAdmin
than using a heavy js library (although they are usually in the cache of every web
user if from google-cdn).

Well, I think it's no problem if loading a tooltip takes a second and loads it via
ajax for example. The typo3 backend for example uses tooltips like that. They display
"loading" in the tooltip until the text is loaded. But of course this would require
js again. But a fallback link-solution is always possible.

At least at the moment, I think heavier pages is not such a problematic issue. We have
less than 3KB of help texts in total and most pages would only require a small fraction
of tooltips. Every JS to display tooltips would be more heavy (but also cacheable).
Alt- and title-texts are always included in HTML as well.

The panel is also okay in my opinion. I think it should either be placed at the bottom
or right. I would not load the complete scrollable help-texts in the panel but only
the one help text corresponding to what the user clicked on.
And I would add a close-button to it.

Reported by crazy4chrissi on 2013-02-12 21:35:37

[dreadnaut]

To summarise, we are considering three non-modal options to improve over popup windows:

- CSS tooltips
  * degrade to a line of text if css is disabled (very rare, anyway)
  * only short text
  * text must be hidden in the page html near the relative "[?]" link, it is shown
on hover via css (on tap on touch devices)
  * no delay
  * no javascript

- Javascript tooltips
  * degrade to new tab/new page link
  * only short text
  * small js footprint (single XHR request)
  * delay to load the content from the server
  * appear on hover or on click

- Javascript panel
  * degrades to new tab/new page link
  * larger area for text
  * small js footprint (single XHR request)
  * delay to load the content from the server
  * appears on click, requires "close" button
  * always appears in the same place

Small changes on the php side would be necessary for all three, but nothing major and
only related to the rendering of "[?]" links.

Reported by dreadnaut on 2013-02-12 22:46:38

[dreadnaut]

I've started working on the tooltip look and I realized that it would be really difficult
to fit helpful text in a small area: we would end up with large <div>s floating in
the middle of the page :|

So I went back to the side panel to see how it would look like, and how it would affect
the rest of the page when visible. Attached is a *very rough* patch against r340.

Reported by dreadnaut on 2013-02-16 13:07:17

<hr> * Attachment: helppanel-r340.diff

[Christopher Kramer]

Okay, looks okay. The only thing I don't like much is that it stays in front of the
rest. So it does not behave like an additional column but like a message in front of
the page.
From a usability point of view, I think it would be better if it behaved like a column.
Mainly because this is how other applications work like. And if the window-width is
low, it will make important UI-elements invisible, which might confuse users (see screenshot
attached for example).

I think it should either be possible to scroll the main UI or the main UI should get
smaller.

Do you agree?

Reported by crazy4chrissi on 2013-02-16 13:40:39

<hr> * Attachment: phpLiteAdmin_issue176_helppanel.jpg

[dreadnaut]

I can make it behave as a column, pushing the rest of the content left of the same width.
You can try replacing this function at line 2405:

function openHelp(section)
{
    var overlay = document.getElementById('help-overlay');
    overlay.innerHTML = '<p>× Close guide</p><iframe src="<?php echo PAGE; ?>?help=1#'
+ section + '" />';
    document.getElementById('main').style.marginRight = '16em';
    overlay.onclick = function() { overlay.style.display = 'none'; document.getElementById('main').style.marginRight
= '0'; }
    overlay.style.display = 'block';
    return false;
}

(again, rough code to test how it would look like)

Reported by dreadnaut on 2013-02-16 13:55:53

[Christopher Kramer]

Yes, I think this behaves much more like I would expect.

(Only thing is that the tabs at the top do not work well if the window-width is low.
But this is not only something related to your patch but an issue of its own because
it is also a problem if the panel is not visible (see screenshot). I guess we should
introduce a minimal width that makes sure all are visible or make them float into 2
rows nicely if the width is not enough. Probably I will open a separate issue.)

But in general, I really like this side-panel approach. I think we should go for it.

Reported by crazy4chrissi on 2013-02-16 14:58:12

<hr> * Attachment: phpLiteAdmin_tabs_floating.png<br>

[Christopher Kramer]

2 small things I noticed with the current patch:
- invalidates XHTML because of </p> instead of <\/p> in JS
- invalidates XHTML because links to help-messages are not urlencoded, i.e. anchors
contain spaces instead of %20

(I know this is rough code, I just noticed these points and though it would be worth
to write them down)

Reported by crazy4chrissi on 2013-02-20 13:54:13

[dreadnaut]

I've been thinking about this a bit and I still have some doubts, but I am going ahead
with the following:

- replace popups with the side panel, which requires javascript;
- fallback to a separate page that will contain the single tooltip;
- remove "all tooltips" page;
- point the Documentation link to our wiki.

Once I've put my hands on the code and we can try it live, we'll decide what to do
:)

Reported by dreadnaut on 2013-04-01 22:52:45