Replace help popup with in-page text

[GoogleCodeExporter]

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.

Original issue reported on code.google.com by dreadnaut on 11 Feb 2013 at 6:39

Attachments:

• nopopup-r333.diff

[GoogleCodeExporter]

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?

Original comment by crazy4ch...@gmail.com on 12 Feb 2013 at 5:40

• Added labels: Type-Enhancement
• Removed labels: Type-Defect

[GoogleCodeExporter]

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.

Original comment by dreadnaut on 12 Feb 2013 at 6:23

[GoogleCodeExporter]

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?

Original comment by crazy4ch...@gmail.com on 12 Feb 2013 at 6:45

• Changed state: Accepted

[GoogleCodeExporter]

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.

Original comment by dreadnaut on 12 Feb 2013 at 7:21

Attachments:

• bottom-panel.png

[GoogleCodeExporter]

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.

Original comment by crazy4ch...@gmail.com on 12 Feb 2013 at 9:35

[GoogleCodeExporter]

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.

Original comment by dreadnaut on 12 Feb 2013 at 10:46

[GoogleCodeExporter]

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.

Original comment by dreadnaut on 16 Feb 2013 at 1:07

Attachments:

• helppanel-r340.diff

[GoogleCodeExporter]

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?

Original comment by crazy4ch...@gmail.com on 16 Feb 2013 at 1:40

Attachments:

• phpLiteAdmin_issue176_helppanel.jpg

[GoogleCodeExporter]

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)

Original comment by dreadnaut on 16 Feb 2013 at 1:55

[GoogleCodeExporter]

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.

Original comment by crazy4ch...@gmail.com on 16 Feb 2013 at 2:58

Attachments:

• phpLiteAdmin_tabs_floating.png

[GoogleCodeExporter]

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)

Original comment by crazy4ch...@gmail.com on 20 Feb 2013 at 1:54

[GoogleCodeExporter]

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 :)

Original comment by dreadnaut on 1 Apr 2013 at 10:52