Bug 114179 - Concentration, improvement, and templatisation of Bugzilla general user help system. Patch by gerv; r,a=justdave.

7 files changed, 280 insertions, 3 deletions

diff --git a/template/en/default/global/footer.html.tmpl b/template/en/default/global/footer.html.tmpl
index 017e8d810..7baf3207a 100644
--- a/template/en/default/global/footer.html.tmpl
+++ b/template/en/default/global/footer.html.tmpl
@@ -23,8 +23,12 @@
   # This template has no interface. However, you must fulfill the interface to
   # global/useful-links.html.tmpl.
   #%]
+
+[% INCLUDE "global/help.html.tmpl" %]
   
-[%# Migration note: this whole file corresponds to the old Param 'footerhtml' %]
+[%# Migration note: below this point, this file corresponds to the old Param
+  # 'footerhtml' 
+  #%]
   
 <table border="0">
   <tr>
diff --git a/template/en/default/global/header.html.tmpl b/template/en/default/global/header.html.tmpl
index ed133140d..825f3c333 100644
--- a/template/en/default/global/header.html.tmpl
+++ b/template/en/default/global/header.html.tmpl
@@ -69,6 +69,8 @@
       </script>
     [% END %]
     
+    [%+ INCLUDE "global/help-header.html.tmpl" %]        
+
     [% IF style %]
       <style type="text/css">
         [% style %]
diff --git a/template/en/default/global/help-header.html.tmpl b/template/en/default/global/help-header.html.tmpl
new file mode 100644
index 000000000..3cbb4e371
--- /dev/null
+++ b/template/en/default/global/help-header.html.tmpl
@@ -0,0 +1,88 @@
+<!-- 1.0@bugzilla.org -->
+[%# The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Bug Tracking System.
+  #
+  # The Initial Developer of the Original Code is Netscape Communications
+  # Corporation. Portions created by Netscape are
+  # Copyright (C) 1998 Netscape Communications Corporation. All
+  # Rights Reserved.
+  #
+  # Contributor(s): Gervase Markham <gerv@gerv.net>
+  #%]
+
+[% IF help %]
+  [% IF user_agent.search("Mozilla/5") %]
+    <style type="text/css">
+    .help {
+        border-style: solid;
+        border-color: #F0A000;
+        background-color: #FFFFFF;
+        padding: 5;
+        position: absolute;
+    }
+    </style>
+
+    <script type="application/x-javascript">
+    var currentHelp;
+
+    function initHelp() {
+        for (var i = 0; i < document.forms.length; i++) {
+            for (var j = 0; j < document.forms[i].elements.length; j++) {
+                [%# MS decided to add fieldsets to the elements array; and 
+                  # Mozilla decided to copy this brokenness. Grr. 
+                  #%]
+                if (document.forms[i].elements[j].tagName != 'FIELDSET') {
+                    document.forms[i].elements[j].onmouseover = showHelp;
+                }
+            }
+        }
+
+        document.body.onclick = hideHelp;
+    }
+
+    function showHelp() {      
+        hideHelp();
+        var newHelp = document.getElementById(this.name + '_help');
+        if (newHelp) {
+            currentHelp = newHelp;
+
+            var mytop = this.offsetTop;
+            var myleft = this.offsetLeft;
+            var myparent = this.offsetParent;
+            while (myparent.tagName != 'BODY') {
+                mytop = mytop + myparent.offsetTop;
+                myleft = myleft + myparent.offsetLeft;
+                myparent = myparent.offsetParent;
+            }
+
+            currentHelp.style.top = mytop + this.offsetHeight + 5;
+            currentHelp.style.left = myleft;
+            currentHelp.style.display='';
+        }
+    }
+
+    function hideHelp() {
+        if (currentHelp) {
+            currentHelp.style.display='none';
+        }
+    }
+    </script>
+  [% END %]
+[% ELSE %]
+  <script type="text/javascript">
+  <!--
+  [%# Avoid warnings by having a dummy function %]
+  function initHelp() {}
+  // -->
+  </script>
+[% END %]
+
diff --git a/template/en/default/global/help.html.tmpl b/template/en/default/global/help.html.tmpl
new file mode 100644
index 000000000..2e43bcee6
--- /dev/null
+++ b/template/en/default/global/help.html.tmpl
@@ -0,0 +1,31 @@
+<!-- 1.0@bugzilla.org -->
+[%# The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Bug Tracking System.
+  #
+  # The Initial Developer of the Original Code is Netscape Communications
+  # Corporation. Portions created by Netscape are
+  # Copyright (C) 1998 Netscape Communications Corporation. All
+  # Rights Reserved.
+  #
+  # Contributor(s): Gervase Markham <gerv@gerv.net>
+  #%]
+                  
+[% IF help %]
+  [% IF user_agent.search("Mozilla/5") %]
+      [% FOREACH h = help_html %]
+      <div id="[% h.id %]_help" class="help" style="display: none;">
+        [%- h.html -%]  
+      </div>
+      [% END %]
+  [% END %]
+[% END %]
+
diff --git a/template/en/default/search/search-advanced.html.tmpl b/template/en/default/search/search-advanced.html.tmpl
index 4dd197218..6390741e3 100644
--- a/template/en/default/search/search-advanced.html.tmpl
+++ b/template/en/default/search/search-advanced.html.tmpl
@@ -27,11 +27,37 @@
 
 [% PROCESS global/header.html.tmpl 
   title = "Search for bugs"
-  onload = "selectProduct(document.forms['queryform']);"
+  onload = "selectProduct(document.forms['queryform']);initHelp();"
 %]
 
 [% button_name = "Search" %]
 
+[%# The decent help requires Javascript %]
+[% IF NOT help %]
+  <p>
+  [% IF user_agent.search("Mozilla/5") %]
+    <script> <!--
+      document.write("<a href='query.cgi?help=1'>Give me some help</a> (reloads page.)");
+      // -->
+    </script>
+    <noscript>
+      <a href="queryhelp.cgi">Give me help</a> with this form.
+    </noscript>
+  [% ELSE %]
+      <a href="queryhelp.cgi">Give me help</a> with this form.
+  [% END %]
+  </p>
+[% ELSE %]
+  <p>
+      For help, mouse over the page elements.
+      <font color="red">
+      [% IF user_agent.match("Mozilla/5") %]
+        Note that if the help popups are hidden by form element scroll bars,
+        this is a bug in your browser, not in Bugzilla.
+      [% END %]
+    </font>    
+  </p>
+[% END %]     
 <form method="get" action="buglist.cgi" name="queryform">
   
 [% PROCESS search/form.html.tmpl %]
@@ -48,4 +74,6 @@
 
 </form>
 
+[% PROCESS "search/search-help.html.tmpl" IF help %]
+
 [% PROCESS global/footer.html.tmpl %]
diff --git a/template/en/default/search/search-help.html.tmpl b/template/en/default/search/search-help.html.tmpl
new file mode 100644
index 000000000..557209690
--- /dev/null
+++ b/template/en/default/search/search-help.html.tmpl
@@ -0,0 +1,96 @@
+<!-- 1.0@bugzilla.org -->
+[%# The contents of this file are subject to the Mozilla Public
+  # License Version 1.1 (the "License"); you may not use this file
+  # except in compliance with the License. You may obtain a copy of
+  # the License at http://www.mozilla.org/MPL/
+  #
+  # Software distributed under the License is distributed on an "AS
+  # IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
+  # implied. See the License for the specific language governing
+  # rights and limitations under the License.
+  #
+  # The Original Code is the Bugzilla Bug Tracking System.
+  #
+  # The Initial Developer of the Original Code is Netscape Communications
+  # Corporation. Portions created by Netscape are
+  # Copyright (C) 1998 Netscape Communications Corporation. All
+  # Rights Reserved.
+  #
+  # Contributor(s): Gervase Markham <gerv@gerv.net>
+  #%]
+  
+[% help_html = [ 
+{ id => "short_desc_type", 
+  html => "The type of summary search you would like" },   
+{ id => "short_desc", 
+  html => "The bug summary is a short sentence which succinctly describes <br> 
+           what the bug is about." },   
+{ id => "product", 
+  html => "Bugs are categorised into Products and Components. Product is the<br>
+           top-level categorisation." },   
+{ id => "component", 
+  html => "Components are second-level categories; each belongs to a<br> 
+           particular Product. Select a Product to narrow down this list." },   
+{ id => "version", 
+  html => "The version field defines the version of the software the bug<br>
+           was found in." },   
+{ id => "target_milestone", 
+  html => "The target_milestone field is used to define when the engineer<br>
+           the bug is assigned to expects to fix it." },   
+{ id => "long_desc", 
+  html => "Bugs have comments added to them by Bugzilla users. You can<br> 
+           search for some text in those comments." },   
+{ id => "long_desc_type", 
+  html => "The type of comment search you would like" },   
+{ id => "bug_file_loc", 
+  html => "Bugs can have a URL associated with them - for example, a pointer<br>
+           to a web site where the problem is seen." },   
+{ id => "bug_file_loc_type", 
+  html => "The type of URL search you would like" },   
+{ id => "status_whiteboard", 
+  html => "Each bug has a free-form single line text entry box for adding<br>
+           tags and status information." },   
+{ id => "status_whiteboard_type", 
+  html => "The type of whiteboard search you would like" },   
+{ id => "keywords", 
+  html => "You can add keywords from a defined list to bugs, in order to<br>
+           tag and group them." },   
+{ id => "keywords_type", 
+  html => "The type of keyword search you would like" },   
+{ id => "bug_status", 
+  html => "A bug may be in any of a number of states." },   
+{ id => "resolution", 
+  html => "If a bug is in a resolved state, then one of these reasons will<br>
+           be given for its resolution." },   
+{ id => "bug_severity", 
+  html => "How severe the bug is, or whether it's an enhancement." },   
+{ id => "priority", 
+  html => "Engineers prioritise their bugs using this field." },   
+{ id => "rep_platform", 
+  html => "The hardware platform the bug was observed on." },   
+{ id => "op_sys", 
+  html => "The operating system the bug was observed on." },   
+{ id => "email1", 
+  html => "Every bug has people associated with it in different roles.<br>
+           Here, you can search on what people are in what role." },   
+{ id => "email2", 
+  html => "Every bug has people associated with it in different roles.<br>
+           Here, you can search on what people are in what role." },   
+{ id => "bug_id", 
+  html => "You can limit your search to a specific set of bugs." },   
+{ id => "votes", 
+  html => "Some bugs can be voted for, and you can limit your search to bugs<br>
+           with more than a certain number of votes." },   
+{ id => "changedin", 
+  html => "You can search by when bugs have changed - this field defines the<br>
+           timeframe for the search." },   
+{ id => "chfield", 
+  html => "You can search for specific types of change - this field define <br>
+           which field you are interested in changes for." },   
+{ id => "chfieldfrom", 
+  html => "The start time of the timeframe for the change." },   
+{ id => "chfieldto", 
+  html => "The end time of the timeframe for the change." },   
+{ id => "chfieldvalue", 
+  html => "The value the field defined above changed to during that time." },   
+] %]
diff --git a/template/en/default/search/search.html.tmpl b/template/en/default/search/search.html.tmpl
index 4dd197218..6390741e3 100644
--- a/template/en/default/search/search.html.tmpl
+++ b/template/en/default/search/search.html.tmpl
@@ -27,11 +27,37 @@
 
 [% PROCESS global/header.html.tmpl 
   title = "Search for bugs"
-  onload = "selectProduct(document.forms['queryform']);"
+  onload = "selectProduct(document.forms['queryform']);initHelp();"
 %]
 
 [% button_name = "Search" %]
 
+[%# The decent help requires Javascript %]
+[% IF NOT help %]
+  <p>
+  [% IF user_agent.search("Mozilla/5") %]
+    <script> <!--
+      document.write("<a href='query.cgi?help=1'>Give me some help</a> (reloads page.)");
+      // -->
+    </script>
+    <noscript>
+      <a href="queryhelp.cgi">Give me help</a> with this form.
+    </noscript>
+  [% ELSE %]
+      <a href="queryhelp.cgi">Give me help</a> with this form.
+  [% END %]
+  </p>
+[% ELSE %]
+  <p>
+      For help, mouse over the page elements.
+      <font color="red">
+      [% IF user_agent.match("Mozilla/5") %]
+        Note that if the help popups are hidden by form element scroll bars,
+        this is a bug in your browser, not in Bugzilla.
+      [% END %]
+    </font>    
+  </p>
+[% END %]     
 <form method="get" action="buglist.cgi" name="queryform">
   
 [% PROCESS search/form.html.tmpl %]
@@ -48,4 +74,6 @@
 
 </form>
 
+[% PROCESS "search/search-help.html.tmpl" IF help %]
+
 [% PROCESS global/footer.html.tmpl %]