Context-sensitive Help (triggered by f1, help buttons in some dialogs) (PDT approved to checkin)

VERIFIED FIXED

Status

SeaMonkey
Help Documentation
P3
enhancement
VERIFIED FIXED
18 years ago
13 years ago

People

(Reporter: BenB, Assigned: Ian Oeschger (gone))

Tracking

({helpwanted})

Trunk
helpwanted
Dependency tree / graph

Firefox Tracking Flags

(Not tracked)

Details

(Whiteboard: nsbeta1)

Attachments

(11 attachments)

1.91 KB, patch
Details | Diff | Splinter Review
1.91 KB, patch
Details | Diff | Splinter Review
3.44 KB, patch
Details | Diff | Splinter Review
3.00 KB, text/html
Details
11.12 KB, patch
Details | Diff | Splinter Review
28.04 KB, patch
Details | Diff | Splinter Review
1.80 KB, patch
Details | Diff | Splinter Review
28.84 KB, patch
Details | Diff | Splinter Review
28.51 KB, patch
Details | Diff | Splinter Review
5.52 KB, patch
Details | Diff | Splinter Review
3.69 KB, patch
Details | Diff | Splinter Review
(Reporter)

Description

18 years ago
Implement infrastructure to provide context-sensitive help, i.e. allow app
developers to provide a away to access extended information about a certain
topic, e.g. via a "Help" button or clicking on labels in dialogs.

Implementation should be easy: Just create some simple chrome for the Help
window (if it doesn't already exist) and give a way to jump directly to a
certain topic, e.g. via |window.open("chrome://mypackage/myhelpfile.html#topic",
...)|. Or am I missing soemthing?

Taking bug for now, but helpwanted.
(Reporter)

Updated

18 years ago
Status: NEW → ASSIGNED
Keywords: helpwanted

Comment 1

18 years ago
Ian Oeschger has reportedly produced a simple Help window, CCing him.

Ideally, you'd have the following.

* A "title" attribute for XPToolkit widgets. (Usually, the value of the title
  attribute would be one or two entities taken from the DTD for that bit of
  interface.) The title would be shown as tooltips/balloons if `Show Help Tips'
  (on Windows and X) or `Show Balloons' (on Mac OS) was turned on in the `Help'
  menu.

* A button class="help" in XPToolkit, which would appear as a normal button on
  Windows and X (with the text `Help', if no text was specified), and as the
  normal Help button (question mark inside a circle) on Mac OS. (OS-specific
  positioning for it could be built in to dialogOverlay.xul or whatever it's
  called.)

* An easy way of making a Help button open the Help window at a given page of the
  local documentation (or even at a remote URL).
(Reporter)

Comment 2

18 years ago
Mattew,
- 1 works (see Prefs|Mailnews|Viewing|structs/smilies)
- this bug is about 3
- 2 is nice-to-have (app developer should certainly specify this class)
(Reporter)

Comment 3

18 years ago
Problem i ran into while trying to implement bug 52222:
- Commondialog doesn't allow for a help button. If make one of the (2) "custom"
buttons the help button (the solution I had to take), it will end up in the
middle between OK and Cancel on Win and Unix. Non-trivial to fix.
- No Help Window chrome. Trivial.
- Modality. If I specify "modal", the user can't access the original dialog
while the help window is open. If I don't specify "modal", the user can't access
the help window at all. Should we fix this? How? Will be extremely difficult to
fix.

Updated

18 years ago
Depends on: 52778

Comment 4

18 years ago
[Taking QA from the departed Eli.]

> - Commondialog doesn't allow for a help button.

Filed bug 52778.

> - No Help Window chrome. Trivial.

IIRC, Ian Oeschger had a minimal XUL help window working several months ago. Ask 
him.

> Modality. If I specify "modal", the user can't access the original dialog
> while the help window is open.

Help should never be modal. That's like a driving instructor making you stop the 
car every time he says something to you.

>                                If I don't specify "modal", the user can't
> access the help window at all.

Why not?
QA Contact: elig → mpt
(Reporter)

Comment 5

18 years ago
> Filed bug 52778.

Tnx.

> IIRC, Ian Oeschger had a minimal XUL help window working several months ago.
> Ask him.

*ask*

> > If I don't specify "modal", the user can't access the help window at all.
> Why not?

Because the modal dailog opening the help window is still modal and obviously
blocks all other windows (unless a dependant window get modal, what I did).
Propably, there's no intrastructure for 2 top-level windows being accessible,
but at the same time blocking the rest.

OTOH, I just realised that the modality of teh askSendFormat is propably wrong
in the first place - it blocks all of Mozilla, which makes no sense. I don't
know, if that makes sense in *any* case. Need to investiagte.
spam: mass-moving currently open help bugs to Terri, who now does qa on 'em. :)
QA Contact: mpt → tpreston

Comment 7

18 years ago
Ben, Matthew: The problem of calling a Help window from modal dialog is a 
long-standing headache that no one has ever solved satisfactorily. Notice that 
if you open a control panel on a Windows machine, there's no Help button. 
There's a reason for that... Now click the F1 (help) key. You get a snippet of 
help that goes away as soon as you click the mouse or press a key.

I've been a designer and writer of online help for something like 10 years now, 
and I used to advocate Help buttons in dialogs. But I would not take this one 
on, for two reasons. (1) Many dialogs that are modal, shouldn't be. I'd solve 
that problem first. (2) The remaining dialogs that *should be* modal probably 
shouldn't have Help buttons -- instead, they should be designed and written in 
such a way as to be crystal clear.

I think we need to move beyond the notion of putting Help buttons in dialogs. 
Information on how to use an interface should be imbedded in the interface 
itself. The online help should simply be a set of questions users can ask about 
*tasks* -- not (for instance) "How do I use the Fonts preferences dialog?" -- 
that's not a real user task. Online help should concentrate on tasks like, "How 
do I change the font my browser uses to display web pages?  (Of course, this 
isn't a great example at the moment, since Fonts preferences isn't working.)

BTW, True context-sensitive online help isn't just a matter of bringing up a 
paragraph of information on (say) mail servers when the user clicks a Help 
button in the mail server preferences panel. To see true context sensitive help, 
you have to look at Apple Guide on the Mac OS. Apple Guide knows what hardware 
the user has, which windows are open, what steps the user has already followed 
(so the help system skips those steps), and so on. Too bad Apple didn't support 
Apple Guide.

BTW(2) You could say that the Mac OS satisfactorily solves the problem of 
opening a help window from a modal dialog. However, the people working on the 
machinery that gets the job done might not agree that what they must go through 
qualifies as "satisfactory."
(Reporter)

Comment 8

18 years ago
verah, thanks for that little "essay". Appreciated. I agree with much you said.

> 1) Many dialogs that are modal, shouldn't be. I'd solve that problem first

Completely agreed. IMO, this applies to almost all modal dialogs in Mozilla.
They just block the current *task* (e.g. the mail composer, if something during
Send goes wrong), not the whole app suite. Why should I be unable to browse or
read new mail, while I enter a subject for the mail I just tried to send
(accidently without a subject)?
The only really modal dialogs are fatal application errors, like low memory.

If the dialog is modal to the current task only, it is easy to opne a new
browser or help chrome window to display the help, and the user can switch
between both.

> I think we need to move beyond the notion of putting Help buttons in dialogs. 
> Information on how to use an interface should be imbedded in the interface 
> itself.

"move beyond" - crap alert ;) In fact, I don't buy that as-is.

Of course, Help buttons are a nice excuse for bad UI. But by trying to embed all
information into the UI, you easily overload it. This is especially true since
there are users with different levels of knowledge (and users quickly
"transform" into another group). A help text might be very useful the first  1
or 2 times, but after you saw it 100 times, it is distracting and this
counter-productive.

Extreme example: What do you do with user who doesn't know what a mail server,
or even a server, is?
Another example: While wizard are said to be helpful for new users (propably
because of the embedded extensive texts), the new account wizard in Mailnews is
bad UI for me. I have to do much more clicks than necessary (for all those Next
buttons), and it doesn't offer all options I need (most notably the "mail server
dir"), so I have to go to the account details anyway later, or Mailnews will try
to "download" all files in my home dir on the server, not just the mail folders.

So, I do think that Help buttons are good for background info or more extensive
help for newbies without harming more experienced users. Kind of "hyperlinking"
- more details on request.

> The online help should simply be a set of questions users can ask about 
> *tasks*

You are mixing up 2 types of help here. Context-sensitive help is destinctively
different from the help manual. They are not exclusive.

BTW: I don't know the MacOS (unfortunately, because I don't have a Mac
*machine*), so please describe anything important you reference.

Comment 9

18 years ago
Ben, you are confused. Online help does *not* equal "the help manual." I'd 
suggest a "Help 101" course. And, when responding to people's comments, don't 
use the word "crap" -- it tends to end the conversation, which is (in any event) 
ending now.
(Reporter)

Comment 10

18 years ago
huh?

> don't use the word "crap"

I didn't mean to suggest that any part of your comment were crap. I'm sorry that
I gave this impression.

(Why do people always hop on the negative parts and oversee the postive ones,
like "appreciated"?)

> Online help does *not* equal "the help manual."

What did you mean with "Online help", then?

Comment 11

18 years ago
I agree with everything Ben has has said here. Putting help text in the UI itself 
is just annoying, once the users become advanced enough to want to use that 
screen real estate for something else. And if it was possible in the real world 
to design any dialog to be `crystal clear' enough that no user ever needed help 
with it, then there would be no reason not to apply the same standard to the rest 
of the UI too -- in which case we wouldn't need user help at all.

Mac OS uses Help extensively in its modal dialogs, and there is nothing stopping 
Windows from doing so either. Why? Simple. The help viewer is a separate app (on 
the OS level), and as such is not affected by the app-modality of the dialog. 
Unfortunately XPToolkit doesn't allow for this -- yet. See bug 54356.
(Reporter)

Comment 12

18 years ago
> See bug 54356.

This is not really the right bug. A bug specific about changing the meaning of
"modal" would be better (see  one of my posts to .xpfe), and this bug could
depend on it. I might file it some time, if nobody else does earlier.
(Reporter)

Comment 13

17 years ago
Changing personal priorities. Giving away most of my bugs :-( (reassigning to
default owner).

I will still track these bugs closely. If you need my input, feel free to ask me.

New owner: Please do *not* close these bugs (as WONTFIX or whatever you may
find) unless they are fixed. Rather, reassign to <nobody@mozilla.org>, if you
don't want to work on them.
Assignee: mozilla → verah
Status: ASSIGNED → NEW
(Assignee)

Comment 14

17 years ago
Accepting bug. We are discussing and working on context-sensitive help.
Brian, cc'ing you on here for lack of a better name@ActiveState.com. 
Status: NEW → ASSIGNED
(Assignee)

Comment 15

17 years ago
taking this bug on c-s-help. See spec-in-progress at
www.mozilla.org/projects/help-viewer/cshelp_specification.html
Assignee: verah → oeschger
Status: ASSIGNED → NEW

Updated

17 years ago
Summary: Context-sensitive Help → Context-sensitive Help (triggered by f1, help buttons in some dialogs)
(Assignee)

Updated

17 years ago
Status: NEW → ASSIGNED
(Assignee)

Comment 16

17 years ago
Adding dependency to 80745: new bug to track problems with chrome:// urls that
include targets (#) do not resolve correctly.
Depends on: 80745
(Assignee)

Comment 17

17 years ago
Created attachment 36739 [details] [diff] [review]
sample of some code to call context-sensitive help from pref.xul
(Assignee)

Comment 18

17 years ago
Note that the patch above is a sample. It will not work if you use it right now, because the function is uses to open Help, openHelp(URI), is not yet available in help.js
(Assignee)

Comment 19

17 years ago
Created attachment 36756 [details] [diff] [review]
update to the patch above
(Assignee)

Updated

17 years ago
Blocks: 67376
(Assignee)

Comment 20

17 years ago
Created attachment 37104 [details] [diff] [review]
update to help.js: openHelp() function to be called from cs help
(Assignee)

Comment 21

17 years ago
Context-sensitive help is in danger of not making it in! Help!

The last couple of patches I have submitted here (to pref.xul and to help.js, respectively) show the code I need to have reviewed and checked in on the UI side (pref.xul) and on the help side so we can load special content from a button. 

It's less elegant than we planned, it doesn't include selection in the TOC (b/c we don't have time to retool with XUL right now, without which we don't have the content model in the toc to get to with selection), and it's a little hacky on the preferences panel side (where there is no ready-made help button of the kind I suggested in 52278), but we really need to get something working right away.

Please, if you have some expertise on the UI side, if you can review or super-review this code (cc'd a couple extra likely candidates for this: blake? smfr? ben?), or if you can help out with some of the implementation stuff--like in the platform specific looks to the Help button, in the localization, or whatever--let me know so we can get _something_ going this week. Thanks.

In short, the patches here suggest that dialogs that want contextual help should: import the help.js script, put their own help button at the bottom, and call openHelp(chrome://help/content/help.xul?special_context), where "?special_context" is a key that you, me, or maybe a help author have put at the top of the help.js file and that will resolve to some particular HTML file.

I will post a document describing this in greater detail here.
(Assignee)

Comment 22

17 years ago
Created attachment 37106 [details]
brief explanation of proposed context-sensitive help system, such as it is
(Assignee)

Comment 23

17 years ago
OK. Talked this over with smfr some (thanks again, Simon!). The following patch
replaces the other ones. It's the uber-patch. Describes a new set of buttons
available from the dialogOverlay, "okCancelHelpButtons", which call "onHelp()"
back on the parent dialog, in this case pref.xul. In pref.xul, onHelp() figures
out which preferences panel is loaded and passes along a particular context to
openHelp(), which is defined in help.js and imported into the parent dialog
pref.xul.

I am proposing this as a general way to do context-sensitive help. The patch, if
accepted, would take care of this for pref.xul, where context-sensitive help
needs to be called for each pref panel.

Every other dialog that wants to use the Help button has to implement an
onHelp() in their own script. They can import chrome://help/content/help.js and
have their onHelp() pass context to the openHelp() function defined there.

I have only done the dialogOverlay for win. I need help with the other
platforms. Also need to finish the list of context "keys" in pref-help.js. Also
need a super review and an r=someone or two. Thanks a lot. -i.
(Assignee)

Comment 24

17 years ago
Created attachment 37126 [details] [diff] [review]
patch for adding context-sensitive help and help buttons to dialog overlay
Make sure to create a *Right variety, as most of our dialogs on windows and mac
at least have right-aligned buttons. Be careful when doing any dialog
conversions that dialogs that have right aligned buttons should have right
alined OK/Cancel buttons after your change ;) 

I agree with blake that we could do something in XBL, but that can come with my
scheduled <dialog/> work post 0.9.3. 
(Assignee)

Comment 26

17 years ago
Created attachment 37267 [details] [diff] [review]
full patch for adding help button(s) to dialog overlays and cs-help to pref.xul

Comment 27

17 years ago
Created attachment 37276 [details] [diff] [review]
Better patch for Mac platformDialogOverlay.xul

Comment 28

17 years ago
Attachment 37276 [details] [diff] provides a better patch for Mac, with left-aligned Help buttons 
like this:

 [Help]               [Cancel]  [OK]

Ian's last patch is missing an entity in platformDialogOverlay.dtd for Mac:

Index: mozilla/xpfe/global/resources/locale/en-US/mac/platformDialogOverlay.dtd
===================================================================
RCS file: /cvsroot/mozilla/xpfe/global/resources/locale/en-US/mac/
platformDialogOverlay.dtd,v
retrieving revision 1.2
diff -b -u -2 -r1.2 platformDialogOverlay.dtd
--- platformDialogOverlay.dtd	2000/02/12 03:33:38	1.2
+++ platformDialogOverlay.dtd	2001/06/06 00:01:30
@@ -4,4 +4,5 @@
 <!ENTITY okButton.label			"OK"> 
 <!ENTITY cancelButton.label		"Cancel"> 
+<!ENTITY helpButton.label		"Help"> 
 
 <!-- Key labels, for mousewheel prefs -->
(Assignee)

Comment 29

17 years ago
Created attachment 37278 [details] [diff] [review]
second take: this one includes DTDs for all plats and replaces my earlier patch

Comment 30

17 years ago
r=sfraser
(Assignee)

Comment 31

17 years ago
Created attachment 37284 [details] [diff] [review]
sorry. one more. This one combines my latest and simon's mac update. It is _the_ patch.

Comment 32

17 years ago
It's possible that some of those unchecked parentNode's could throw warnings in 
some cases (unlikely).

Remove the deadly tabs, and sr=blake, with the assurance that this will be 
converted to xbl.

Comment 33

17 years ago
Forgot to mention: align= is deprecated, should be using orient=

And won't opening a non-modal dialog from a modal one cause problems on some 
platforms (mac?)?
(Assignee)

Comment 34

17 years ago
Modality issue: in the help.js's openHelp() function, which is the way we'd like
people to open the help window from their dialogs, we replaced the ordinary
window.open(blah blah, dialog=no, blah) with Folger's Instant Crystals:
window.opener.open(blah blah, dialog=no, blah).

This makes the Help window non-modal to the browser window, so you can move back
and forth between help & preferences+browser, but preferences is still modal to
the browser. Still not very pretty. But this is as loose as we can get barring a
change to the modality of preferences. I'd like to see how this works on mac
(smfr? you there?) and whether this is something we ought to implement (if we
can get this checked in!)

Comment 35

17 years ago
I suspect that Mac may be unhappy trying to open a non-modal window in front of a 
modal one (help over prefs dialog). Maybe danm can reassure us? I'll test.

Comment 36

17 years ago
using window.opener.open() in the help.js kinda works OK on Mac. When you hit the 
Help button in prefs, the Help window opens in the front. But after clicking on 
the prefs dialog, it comes to the front, and you can no longer interact with the 
help window.

However, I think that using window.opener.open() is bad, because you cannot 
guarantee that you are always invoking help from a dialog; we might have help 
invoked from the menubar or a main window, so window.opener() would be null.

The help window also has issues; it has no menu bar, yet, on Mac, the top-level 
menus remain active (view source has the same issue). And it has no key 
shortcuts, so I can't close it with the keyboard.
(Assignee)

Comment 37

17 years ago
Well, can the r=smfr and sr=blake stick if I do?: 

if (window.opener)
 { 
    window.opener.open(blah blah); 
 } else { 
    window.open(blah blah); 
}?

The issues you mention, Simon, are issues about the Help window generally
(though I suppose they may be exacerbated by the layering of windows in
context-sensitive help). I believe there is a bug for them...hmmm can't find it
now. May be over on the bugscape side.

Comment 38

17 years ago
(attempt to reassure sfraser; comment at 11:43) I can't check right now but modal 
in front of modal should work. We do it all over the @##%* place. Even nonmodal 
in front of modal should work (the nonmodal window is forced to be modal).

Comment 39

17 years ago
a= asa@mozilla.org for checkin to the trunk.
(on behalf of drivers)
Blocks: 83989

Updated

17 years ago
Blocks: 86548
(Assignee)

Comment 40

17 years ago
context-sensitive help support was checked in yesterday afternoon (6/19). It
provides a help button in the preferences panel that loads appropriate content
in the help viewer...pretty much. 

I put a doHelpButton() function in pref-help.js (newly loaded in the pref.xul)
that calls openHelp() from help.js (now also loaded there).

I have some updates to the pref-help.js file where the "keys" to the content are
defined. The Advanced panels, some of the security panels, and the Smart
Browsing panel were not loading content. The patch for this follows.
(Assignee)

Comment 41

17 years ago
Created attachment 39397 [details] [diff] [review]
additions to the panel-->help keys
(Assignee)

Comment 42

17 years ago
blake: if you get a sec...TIA

Updated

17 years ago
Summary: Context-sensitive Help (triggered by f1, help buttons in some dialogs) → Context-sensitive Help (triggered by f1, help buttons in some dialogs) (PDT approved to checkin)
Whiteboard: nsbeta1
(Assignee)

Comment 43

17 years ago
These panel->key updates went in with content updates this afternoon. All or 
almost all of the items should be hooked up to help content, or else fail to the 
basic "Preferences Help" page.

(Assignee)

Comment 44

17 years ago
Created attachment 40312 [details] [diff] [review]
patch for adding help buttons to os2 plat as well

Comment 45

17 years ago
we can't do this to os/2 a= asa@mozilla.org for checkin to 0.9.2 branch pending
review.
(
rs=blizzard

Comment 47

17 years ago
r=mkaply on the OS/2 patch
(Assignee)

Comment 48

17 years ago
Marking FIXED. F1 feature to be added is tracked in 88739, the full
extensionalizing of the help system is in 89603, and various other bugs have the
rest. The context-sensitive help buttons exist in dozens of dialogs, are
available in the global overlay for use elsewhere, and the pesky modality issue
was resolved.

Status: ASSIGNED → RESOLVED
Last Resolved: 17 years ago
Resolution: --- → FIXED

Comment 49

15 years ago
v
Status: RESOLVED → VERIFIED
Product: Browser → Seamonkey
You need to log in before you can comment on or make changes to this bug.