Closed Bug 114179 Opened 23 years ago Closed 22 years ago

Concentration, improvement, and templatisation of Bugzilla general user help system

Categories

(Bugzilla :: User Interface, enhancement, P3)

Product:
Bugzilla
Component:
User Interface
Type:
enhancement

Tracking

()

Status:
RESOLVED FIXED
Milestone:
Bugzilla 2.18

People

(Reporter: netdragon, Assigned: netdragon)

References

Details

Attachments

(1 file, 4 obsolete files)

Patch v.4
13.01 KB, patch
justdave
: review+
Details | Diff | Splinter Review 
This bug will be assigned to me. I was thinking about bug 88788, and I 
thought - why not extend the sections of queryhelp.cgi into a userhelp.cgi 
that has different sections based on the parameters passed. Included on this 
could be bug_status.html and any other help file that is used as context help 
for Mozilla. 

Also, I think that every field possible should have a link, such as on 
enter_bug.cgi, CC, URL, Summary, Reporter, Version and Description.
-> me
Assignee: barnboy → netdemonz
Status: NEW → ASSIGNED
Priority: -- → P3
Target Milestone: --- → Bugzilla 2.18
I've already started work on this. Basically, what is happening is there are
sections and subsections. The sections and subsection to go to is sent as a
parameter, and the contents for that section expanded in the table of contents
on the page.

I fooled around and implemented templates on one of my personal sites in order
to learn how they work.
Depends on: 88788
Summary: Concentration of Bugzilla help system for normal Bugzilla users and general improvements → Concentration, improvement, and templatisation of Bugzilla general user help system
Brian - could you expand a bit further on your vision here, and perhaps attach a
working prototype? It would be really bad if you did all this work and we
couldn't use it because it didn't fit in with what we want to do.

For example, I had an idea about how to do the help on query.cgi which is
totally different to what's been done before. We should start a discussion about
this in the newsgroup.

Gerv
What about adding a smaller-font-size "?" after everything that can be
described, and have a short description in the title tag of the link, and the
link being a pop-up to describe what it is?

Of course, have a user-pref that would shut off this context help.

Something like this would have helped immensly starting out using Bugzilla...
I will attach a prototype of the help system shell when I finish it (without any
real content) and some test content.
For the descriptions of the fields of query.cgi, I am going to use jpgs instead
of html.
No longer depends on: 88788
Brian, have you seen my proposal for a new help system in the newsgroup? It
appears to have got quite a lot of support. Would you consider implementing
something like that?

Gerv
I've just prototyped the system I mentioned in the newsgroups. We can nick the
popup code basically straight from e.g.
http://bonsai.mozilla.org/cvsblame.cgi?file=mozilla/js/jsd/Makefile.in&root=/cvsroot
There's different code for different browsers, but templatisation could deal
with that. We'd have help templates which would get conditionally included in
the key files: query.cgi, show_bug.cgi and maybe buglist.cgi. The JS template
would be common; the <div>s which defined the help content would be page-specific.

Gerv
Component: Documentation → User Interface
Attached patch Patch v.0.5 (obsolete) — — Splinter Review 
This is a work-in-progress; it implements a generic pop-up help system for
Mozilla, and applies it to query.cgi. It should be possible to make the help
system work in other half-decent browsers; the places where browser-specific
forks are necessary are clear and easy to see.

Unfortunately, Mozilla has a problem with dynamically-positioned elements not
being drawn on top of HTML form control scrollbars. This makes bits of our help
text disappear under scrollbars :-(. Also, the help text probably isn't as
polished as it should be.

Note that adding the help system to any form-based page is very easy; you call
initHelp() from the <body> onload handler, write a file defining help text for
each form element's name, and include it. Help is then activated if "help=1" is
a param to the CGI. 

Gerv
Attached patch Patch v.1 (obsolete) — — Splinter Review 
Here's version 1. There's no solution to the scrollbar problem, so we just have
to position the elements to avoid them as far as possible.

To resummarise, adding the help system to any form-based page is done as
follows: 

- call initHelp() from the <body> onload handler
- write a file defining help text for each form element's 'name' (taking
search-help.html.tmpl as a model)
- include it in the template, before the footer. 

Help is then activated if "help=1" is a param to the CGI. You need to provide a
link to enable it.

Gerv
Attachment #92109 - Attachment is obsolete: true
I don't like this being dependant on mozilla, ven though its only temporary, and
I know others won't like this being dependant on js.

I think getting the code to work on ns4 is a lost cause, in which case you may
as well use the w3c interfaces for this sort of stuff.

Can we arrange it so that if js isn't enabled, the help link loads a new page
with just the info from those hashes?

I don't like reloading the page, either - if we do require js, can't you just
call inithelp from an onclick? (and then have the href load a separate page for
non js browsers)
> I don't like this being dependant on mozilla, ven though its only temporary, 
> and I know others won't like this being dependant on js.

The dependency on Mozilla is only because I can't easily test it with other
browsers. Once it's checked in, we can test with other browsers and slacken the
requirement gradually. 

As for the JS dependence, a context-sensitive help system really needs it (well,
you _might_ do something using advanced CSS, but that would _definitely_ be
Mozilla-specific.) We still have the old help for non-JS browsers.

> I think getting the code to work on ns4 is a lost cause, in which case you may
> as well use the w3c interfaces for this sort of stuff.

What changes are you suggesting?

> Can we arrange it so that if js isn't enabled, the help link loads a new page
> with just the info from those hashes?

Currently, it loads queryhelp.cgi - the old help page. Is that OK?

> I don't like reloading the page, either - if we do require js, can't you just
> call inithelp from an onclick? (and then have the href load a separate page 
> for non js browsers)

I don't want to do that because that would mean including the help stuff every
time the page is loaded by anyone. I don't want to make all advanced users pay
the download penalty. Our pages are bloated enough as it is.

Gerv
> [ns4 stuff vs w3c]

document.forms isn't standard, AFAIK. It would be better to use
document.getElementById(), and require ids on the appropriate elements. Or even
do this with the title attribute, rather than js, perhaps.

You could probably do css stuff which would work in ie6, but I don't really know.

> Currently, it loads queryhelp.cgi - the old help page. Is that OK?

Well, yes, in this particular case. It would, however, as part of this
generalisation, be nice if queryhelp was effectivly autogenerated.

Note that if everything in the current queryhelp.cgi is not in the new help
system, then since this file is no longer accessible, you're hiding docs, which
would be bad.

> [reloading the page]

You could load it via xmlrpc + a serialiser, but I see your point. If it were
part of an external js file, though, then it wouldn't count so much, as it would
be a one time download for common pages.

What do others think?

What do others think?
> document.forms isn't standard, AFAIK.

Nothing in DOM Level 0 is a standard. Using document.forms has the significant
advantage that you don't need to mess with the page to add the help system (see
my comment on how easy it is.)

> do this with the title attribute, rather than js, perhaps.

You can't put line breaks in a title. :-( They just aren't suitable for this.

> > Currently, it loads queryhelp.cgi - the old help page. Is that OK?
> 
> Well, yes, in this particular case. It would, however, as part of this
> generalisation, be nice if queryhelp was effectivly autogenerated.

Without the context of the page, more text would be needed anyway.

> Note that if everything in the current queryhelp.cgi is not in the new help
> system, then since this file is no longer accessible, you're hiding docs, 
> which would be bad.

Have you _seen_ the current queryhelp.cgi? It's a monster. There's no way even
1/10 of what's in there is going to be, or needs to be in the new help system.

> You could load it via xmlrpc + a serialiser, but I see your point. If it were
> part of an external js file, though, then it wouldn't count so much, as it 
> would be a one time download for common pages.

The JS yes - but the big download is the help text, which is specific to each
page and so can't be made generic.

Gerv
Comment on attachment 94750 [details] [diff] [review]
Patch v.1

I'm not comfortable with the check of FORM in the generic tempalte code,
although I can't thikn of anything better given our current infrastructure.

I'm really not going to have time to review this; you'd be better of finding
someone else.
Blocks: bz-zippy
*** Bug 177002 has been marked as a duplicate of this bug. ***
Attached patch Patch v.2 (obsolete) — — Splinter Review 
Unrotted version.

Gerv
Attachment #94750 - Attachment is obsolete: true
two problems (also where in previous patch):
1. help parameter in globals.pl doesn't seem to work (it returns 0 all the
time). i had to move it to query.cgi to make it work

after that everything in mozilla was fine, but:
2. internet explorer complains about javascript error "object expected"
after about 20 mintues search, where could possibly be the error ( :)  )
i found that javascript for dummy function is described this way:
<script type="application/x-javascript">

after replacing it to 
<script type="text/javascript">

IE yells no more
Attached patch Patch v.3 (obsolete) — — Splinter Review 
> 1. help parameter in globals.pl doesn't seem to work (it returns 0 all the
> time). i had to move it to query.cgi to make it work

That's probably because of the move to CGI.pm. I've moved this assignment to
the bottom of CGI.pl.

> after that everything in mozilla was fine, but:
> 2. internet explorer complains about javascript error "object expected"

OK - fixed by changing the type for the dummy JS.

Gerv
Attachment #104688 - Attachment is obsolete: true
Comment on attachment 104737 [details] [diff] [review]
Patch v.3

(Replacing review bug 177811 with flag.)

Gerv
Attachment #104737 - Flags: review?(justdave)
Comment on attachment 104737 [details] [diff] [review]
Patch v.3

I'm kind of at a tossup whether to sign off on this or not. :)

It works great in Mozilla.  It doesn't work at all in Internet Explorer (5.2.2
MacOSX).  Nothing happens when I mouse over anything.

Help text for Components should probably mention that you can click on the word
Components to get descriptions of the components, or even provide a link within
the popup.

If it worked in IE I'd r= this in an instant.
Attachment #104737 - Flags: review?(justdave) → review-
I refer the honourable gentleman to the comment I made some months ago:

"The dependency on Mozilla is only because I can't easily test it with other
browsers. Once it's checked in, we can test with other browsers and slacken the
requirement gradually."

The point is, it doesn't _break_ IE. I can't easily test it on IE - so let's
check it in, and then write the proper JS or templates for other browsers and
check that in separately. It's designed to be modular, so the browser-specific
bits are isolated and only have to be written once, no matter how many pages we
use this on.

Gerv
But it still tells the user at the top of the page that they can mouse-over
items to view help on them.  If we know it doesn't work in IE, then we shouldn't
display this text if the user is using IE.  Since that text is being output by
javascript, if there's a certain object you're using that's specific to Mozilla,
just test for the existance of that object, and if it exists you print the
message, if not, then you print a message saying "sorry your browser doesn't
support the popup-help" or something like that.
> But it still tells the user at the top of the page that they can mouse-over
> items to view help on them.  If we know it doesn't work in IE, then we shouldn't
> display this text if the user is using IE.

Fair point. Can I have an r= if I fix that? :-) (The alternative is to give them
a link to queryhelp.cgi, not to say "Your browser doesn't support it").

Gerv
Yes.  r= if that's fixed.
Comment on attachment 104737 [details] [diff] [review]
Patch v.3

>Index: CGI.pl
>===================================================================
>RCS file: /cvsroot/mozilla/webtools/bugzilla/CGI.pl,v
>retrieving revision 1.188
>diff -u -r1.188 CGI.pl
>--- CGI.pl	26 Oct 2002 01:56:55 -0000	1.188
>+++ CGI.pl	31 Oct 2002 08:01:08 -0000
>@@ -901,4 +901,7 @@
>     $::COOKIE{$name} = $::cgi->cookie($name);
> }
> 
>+# This could be needed in any CGI, so we set it here.
>+$vars->{'help'} = $::FORM{'help'} ? 1 : 0;
>+

Repeat after me: |$vars is not a global| :)

While we're at it, $::FORM is deprecated; use $::cgi->param('help') instead

In this case, though, I'm not going to object (since its unconditional);
eventually the cgi object will end up being pushed to the template and we can
then grab the form vars (and user-agent, which is the main reason for this)
manually.
Attached patch Patch v.4 — — Splinter Review 
Displays help link only on Mozilla, and uses $::cgi. Yes, there's a small
amount of redundancy in the template; the alternatives would be worse.

Gerv
Attachment #104737 - Attachment is obsolete: true
if you have |help| as a param, but aren't using moz, then you're not defining
the inithelp function....
> if you have |help| as a param, but aren't using moz, then you're not defining
> the inithelp function....

Yes, but if you aren't using Moz, then the UI for adding "help" as a param isn't
available. Yes, you could hack the URL - but then, you deserver what you get (JS
errors, in this case.)

Patch v.4 is fine for review IMO. :-)

Gerv
Attachment #106472 - Flags: review?(justdave)
Comment on attachment 106472 [details] [diff] [review]
Patch v.4

r=justdave

I have problems with the content of some of the tooltips, but this bug is about
putting the infrastructure in place, we can file new bugs for bad tooltips :-)
Attachment #106472 - Flags: review?(justdave) → review+
a= on this is pending the 2.17.1 release, I want to hold until then to check it
in.  Adding it to my queue so I don't forget.
Flags: approval?
Flags: approval? → approval+
Fixed.

Bug 182082 opened for support on other browsers, and bug 182083 opened to track
support on other Bugzilla pages.

Checking in CGI.pl;
/cvsroot/mozilla/webtools/bugzilla/CGI.pl,v  <--  CGI.pl
new revision: 1.192; previous revision: 1.191
done
RCS file:
/cvsroot/mozilla/webtools/bugzilla/template/en/default/global/help.html.tmpl,v
done
Checking in template/en/default/global/help.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/global/help.html.tmpl,v 
<--  help.html.tmpl
initial revision: 1.1
done
Checking in template/en/default/global/header.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/global/header.html.tmpl,v
 <--  header.html.tmpl
new revision: 1.19; previous revision: 1.18
done
RCS file:
/cvsroot/mozilla/webtools/bugzilla/template/en/default/global/help-header.html.tmpl,v
done
Checking in template/en/default/global/help-header.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/global/help-header.html.tmpl,v
 <--  help-header.html.tmpl
initial revision: 1.1
done
Checking in template/en/default/global/footer.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/global/footer.html.tmpl,v
 <--  footer.html.tmpl
new revision: 1.8; previous revision: 1.7
done
Checking in template/en/default/search/search.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/search/search.html.tmpl,v
 <--  search.html.tmpl
new revision: 1.12; previous revision: 1.11
done
RCS file:
/cvsroot/mozilla/webtools/bugzilla/template/en/default/search/search-help.html.tmpl,v
done
Checking in template/en/default/search/search-help.html.tmpl;
/cvsroot/mozilla/webtools/bugzilla/template/en/default/search/search-help.html.tmpl,v
 <--  search-help.html.tmpl
initial revision: 1.1
done

Gerv
Status: ASSIGNED → RESOLVED
Closed: 22 years ago
Resolution: --- → FIXED
QA Contact: matty_is_a_geek → default-qa
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Creator:
Created:
Updated:
Size: