From 8f4fd271de4edbf1a206dfa0a98f8276f6189709 Mon Sep 17 00:00:00 2001
From: Frédéric Buclin <LpSolit@gmail.com>
Date: Thu, 29 Mar 2012 19:56:41 +0200
Subject: Bug 554819: Quicksearch should be using Text::ParseWords instead of
 custom code in splitString Also fixes QS with accented characters (bug
 730207) r=dkl a=LpSolit

---
 template/en/default/global/user-error.html.tmpl | 21 +++++++
 template/en/default/pages/quicksearch.html.tmpl | 83 ++++++++++++++++++++++---
 2 files changed, 96 insertions(+), 8 deletions(-)

(limited to 'template')

diff --git a/template/en/default/global/user-error.html.tmpl b/template/en/default/global/user-error.html.tmpl
index feff9f042..3d1ac5c53 100644
--- a/template/en/default/global/user-error.html.tmpl
+++ b/template/en/default/global/user-error.html.tmpl
@@ -1448,6 +1448,27 @@
     The name of the query must be less than [% constants.MAX_LEN_QUERY_NAME FILTER html %]
     characters long.
 
+  [% ELSIF error == "quicksearch_invalid_query" %]
+    [% title = "Invalid Query" %]
+    Your query is invalid.
+    [% IF operators %]
+      The [% operators.shift FILTER html %] operator cannot be followed by
+      [%+ operators.shift FILTER html %].
+    [% ELSE %]
+      A query cannot start with AND or OR, nor can it end with AND, OR or NOT.
+      They are reserved operators and must be quoted if you want to look for
+      these strings.
+    [% END %]
+
+  [% ELSIF error == "quicksearch_unbalanced_quotes" %]
+    [% title = "Badly Formatted Query" %]
+    [% terms.Bugzilla %] is unable to parse your query correctly:
+    <em>[% string FILTER html %]</em>.<br>
+    If you use quotes to enclose strings, make sure both quotes are present.
+    If you really want to look for a quote in a string, type \" instead of ".
+    For instance, <em>"I'm so \"special\", really"</em> (with quotes) will be
+    interpreted as <em>I'm so "special", really</em>.
+
   [% ELSIF error == "quicksearch_unknown_field" %]
     [% title = "QuickSearch Error" %]
     There is a problem with your search:
diff --git a/template/en/default/pages/quicksearch.html.tmpl b/template/en/default/pages/quicksearch.html.tmpl
index e6398eade..901f05467 100644
--- a/template/en/default/pages/quicksearch.html.tmpl
+++ b/template/en/default/pages/quicksearch.html.tmpl
@@ -38,7 +38,16 @@
   <input type="submit" value="Search" id="find">
 </form>
 
-<h2>The Basics</h2>
+<ul>
+  <li><a href="#basics">The Basics</a></li>
+  <li><a href="#basic_examples">Examples of Simple Queries</a></li>
+  <li><a href="#fields">Fields You Can Search On</a></li>
+  <li><a href="#advanced_features">Advanced Features</a></li>
+  <li><a href="#shortcuts">Advanced Shortcuts</a></li>
+  <li><a href="#advanced_examples">Examples of Complex Queries</a></li>
+</ul>
+
+<h2 id="basics">The Basics</h2>
 
 <ul class="qs_help">
   <li>If you just put a word or series of words in the search box, 
@@ -89,8 +98,32 @@
     <em>any</em> of those values will be searched for.</li>
 </ul>
 
-<p>You may also want to read up on the <a href="#advanced">Advanced
-  Features</a>.</p>
+<h2 id="basic_examples">Examples of Simple Queries</h2>
+
+<p>Here are some examples of how to write some simple queries.
+  <a href="#advanced_examples">Examples for more complex queries</a> can be
+  found lower in this page.</p>
+
+<ul class="qs_help">
+  <li>All open [% terms.bugs %] where userA@company.com is in the CC list
+    (no need to mention open [% terms.bugs %], this is the default):<br>
+    <kbd>cc:userA@company.com</kbd></li>
+  <li>All unconfirmed [% terms.bugs %] in product productA (putting the
+    [%+ terms.bug %] status at the first position make it being automagically
+    considered as [% terms.abug %] status):<br>
+    <kbd>UNCONFIRMED product:productA</kbd>
+  <li>All open and closed [% terms.bugs %] reported by userB@company.com
+    (we must specify ALL as the first word, else only open [% terms.bugs %]
+    are taken into account):<br>
+    <kbd>ALL reporter:userB@company.com</kbd>
+  <li>All open [% terms.bugs %] with severity blocker or critical with the
+    target milestone set to 2.5:<br>
+    <kbd>severity:blocker,critical milestone:2.5</kbd>
+  <li>All open [% terms.bugs %] in the component Research & Development
+    with priority P1 or P2 (we must use quotes for the component as its name
+    contains whitespaces):<br>
+    <kbd>component:"Research & Development" priority:P1,P2</kbd></li>
+</ul>
 
 <h2 id="fields">Fields You Can Search On</h2>
 
@@ -143,15 +176,18 @@
   </tbody>
 </table>
 
-<h2 id="advanced">Advanced Features</h2>
+<h2 id="advanced_features">Advanced Features</h2>
 
 <ul class="qs_help">
   <li>If you want to search for a <strong>phrase</strong> or something that
-    contains spaces, you can put it in quotes, like:
-    <kbd>"this is a phrase"</kbd>. You can also use quotes to search for
+    contains spaces, commas, colons or quotes, you must put it in quotes, like:
+    <kbd>"yes, this is a phrase"</kbd>. You must also use quotes to search for
     characters that would otherwise be interpreted specially by quicksearch.
-    For example, <kbd>"this|thing"</kbd> would search for the literal phrase
-    <em>this|thing</em>.</li>
+    For example, <kbd>"this|that"</kbd> would search for the literal string
+    <em>this|that</em> and would not be parsed as <kbd>"this OR that"</kbd>.
+    Also, <kbd>"-field:value"</kbd> would search for the literal phrase
+    <em>-field:value</em> and would not be parsed as
+    <kbd>"NOT field:value"</kbd>.</li>
 
   <li>You can use <strong>AND</strong>, <strong>NOT</strong>,
     and <strong>OR</strong> in searches. 
@@ -181,6 +217,12 @@
       </li>
     </ul>
 
+    <p>You cannot use | nor OR to enumerate possible values for a given field.
+      You must use commas instead. So <kbd>field:value1,value2</kbd> does what
+      you expect, but <kbd>field:value1|value2</kbd> would be treated as
+      <kbd>field:value1 OR value2</kbd>, which means value2 is not bound to
+      the given field.</p>
+
     <p>OR has higher precedence than AND; AND is the top level operation.
       For example:</p>
     <p>Searching for <em><kbd>url|location bar|field -focus</kbd></em> means
@@ -271,4 +313,29 @@
   </tbody>
 </table>
 
+<h2 id="advanced_examples">Examples of Complex Queries</h2>
+
+<p>It is pretty easy to write rather complex queries without too much effort.
+  For very complex queries, you have to use the
+  <a href="query.cgi?format=advanced">Advanced Search</a> form.</p>
+
+<ul class="qs_help">
+  <li>All [% terms.bugs %] reported by userA@company.com or assigned to him
+    (the initial @ is a shortcut for the assignee, see the
+    <a href="#shortcuts">Advanced Shortcuts</a> section above):<br>
+    <kbd>ALL @userA@company.com OR reporter:userA@company.com</kbd></li>
+  <li>All open [% terms.bugs %] in product productA with either severity
+    blocker, critical or major, or with priority P1, or with the blocker+
+    flag set, and which are neither assigned to userB@company.com nor to
+    userC@company.com (we make the assumption that there are only two users
+    matching userB and userC, else we would write the whole login name):<br>
+    <kbd>:productA sev:blocker,critical,major OR pri:P1 OR flag:blocker+ -assign:userB,userC</kbd></li>
+  <li>All FIXED [% terms.bugs %] with the blocker+ flag set, but without
+    the approval+ nor approval? flags set:<br>
+    <kbd>FIXED flag:blocker+ -flag:approval+ -flag:approval?</kbd></li>
+  <li>[% terms.Bugs %] with <em>That's a "unusual" issue</em> in the
+    [%+ terms.bug %] summary (double quotes are escaped using <em>\"</em>):<br>
+    <kbd>summary:"That's a \"unusual\" issue"</kbd></li>
+</ul>
+
 [% PROCESS global/footer.html.tmpl %]
-- 
cgit v1.2.3-24-g4f1b