summaryrefslogtreecommitdiffstats
path: root/template/en/default/pages/quicksearch.html.tmpl
blob: 28062b5357264ad6a4d3493a43482ac5c722fb0b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
[%# 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 Everything Solved, Inc.
  # Portions created by the Initial Developer are Copyright (C) 2009
  # the Initial Developer. All Rights Reserved.
  #
  # Contributor(s):
  #   Max Kanat-Alexander <mkanat@bugzilla.org>
  #%]

[% PROCESS "global/field-descs.none.tmpl" %]

[% INCLUDE global/header.html.tmpl
   title  = "$terms.Bugzilla QuickSearch",
   style_urls = ['skins/standard/page.css']         
   onload = 'document.forms[\'f\'].quicksearch.focus()'
 %]

[% USE Bugzilla %]

<p>Type in one or more words (or pieces of words) to search for:</p>

<form name="f" action="buglist.cgi" method="get"
      class='quicksearch_check_empty' data-no-csrf>
  <input type="text" size="40" name="quicksearch">
  <input type="submit" value="Search" id="find">
</form>

<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, 
    [%+ terms.Bugzilla %] will search the 
    [%+ field_descs.product FILTER html %],
    [%+ field_descs.component FILTER html %], 
    [%+ IF use_keywords %][%+ field_descs.keywords FILTER html %],[% END %]
    [%+ IF Param('usebugaliases') %][% field_descs.alias FILTER html %],[% END %]
    [%+ field_descs.short_desc FILTER html %], 
    [%+ IF Param('usestatuswhiteboard') %][% field_descs.status_whiteboard FILTER html %],[% END %]
    and [% field_descs.longdesc FILTER html %] fields for your word or words.</li>

  <li>Typing just a <strong>number</strong> in the search box will take
    you directly to the [% terms.bug %] with that ID. 
    [% IF Param('usebugaliases') %]
      Also, just typing the <strong>alias</strong> of [% terms.abug %]
      will take you to that [% terms.bug %].
    [% END %]
  </li>

  <li>Adding more terms <strong>narrows down</strong> the search, it does not
     expand it. (In other words, [% terms.Bugzilla %] searches for 
     [%+ terms.bugs %] that match <em>all</em> your criteria, not
     [%+ terms.bugs %] that match <em>any</em> of your criteria.)</li>

  <li>Searching is <strong>case-insensitive</strong>. So <kbd>table</kbd>,
    <kbd>Table</kbd>, and <kbd>TABLE</kbd> are all the same.</li>

  <li>[% terms.Bugzilla %] does not just search for the exact word you put in,
    but also for any word that <strong>contains</strong> that word.
    So, for example, searching for "cat" would also find [% terms.bugs %]
    that contain it as part of other words&mdash;for example, [% terms.abug %]
    mentioning "<strong>cat</strong>ch" or "certifi<strong>cat</strong>e". It
    will not find partial words in the [% field_descs.longdesc FILTER html %]
    or [% field_descs.keywords FILTER html %] fields,
    though&mdash;only full words are matched, there.</li>

  <li>By default, only <strong>open</strong> [% terms.bugs %] are
    searched. If you want to know how to also search closed [% terms.bugs %],
    see the <a href="#shortcuts">Advanced Shortcuts</a> section.</li>

  <li>If you want to search <strong>specific fields</strong>, you do it like
    <kbd>field:value</kbd>, where <kbd>field</kbd> is one of the 
    <a href="#fields">field names</a> lower down in this
    document and <kbd>value</kbd> is the value you want to search for
    in that field. If you put commas in the <kbd>value</kbd>, then it is
    interpreted as a list of values, and [% terms.bugs %] that match
    <em>any</em> of those values will be searched for.</li>
</ul>

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

<p>You can specify any of these fields like <kbd>field:value</kbd>
  in the search box, to search on them. You can also abbreviate
  the field name, as long as your abbreviation matches only one field name.
  So, for example, searching on <kbd>stat:VERIFIED</kbd> will find all
  [%+ terms.bugs %] in the <kbd>VERIFIED</kbd> status. Some fields have
  multiple names, and you can use any of those names to search for them.</p>

[% IF Bugzilla.active_custom_fields.size %]
  [% SET first_field = Bugzilla.active_custom_fields.0 %]
  <p>For custom fields, they can be used and abbreviated
    based on the part of their name <em>after</em> the <kbd>cf_</kbd>
    if you'd like, in addition to their standard name starting with
    <kbd>cf_</kbd>. So for example, 
    <kbd>[% first_field.name FILTER html %]</kbd> can be
    referred to as 
    <kbd>[% first_field.name.replace('^cf_') FILTER html %]</kbd>,
    also. However, if this causes a conflict between the standard
    [%+ terms.Bugzilla %] field names and the custom field names, the
    standard field names always take precedence.</p>
[% END %]

[% SET field_table = {} %]
[% FOREACH field = quicksearch_field_names.keys %]
  [% description = field_descs.$field %]
  [% field_table.$description = quicksearch_field_names.${field} %]
[% END %]


<table cellspacing="0" cellpadding="0" border="0" class="qs_fields">
  <thead>
    <tr>
      <th class="field_name">Field</th>
      <th class="field_nickname">Field Name(s) For Search</th>
    </tr>
  </thead>
  <tbody>
    [% FOREACH desc = field_table.keys.sort %]
      <tr>
        <td class="field_name">[% desc FILTER html %]</td>
        <td class="field_nickname">
          [% FOREACH nickname = field_table.$desc %]
            <kbd>[% nickname FILTER html %]</kbd>
            [% ",&nbsp; " UNLESS loop.last %]
          [% END %]
      </tr>
    [% END %]
  </tbody>
</table>

<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, 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|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. 

    You can also use <kbd>-</kbd> to mean "NOT", and <kbd>|</kbd> to mean "OR".
    There is no special character for "AND", because by default any search
    terms that are separated by a space are joined by an "AND".
    Examples:
    <ul>
      <li>
        <strong>NOT</strong>:<br>
        Use <kbd><strong>-</strong><em>summary:foo</em></kbd> to exclude 
        [%+ terms.bugs %] with <kbd>foo</kbd> in the summary.<br>
        <kbd><em>NOT summary:foo</em></kbd> would have the same effect.
      </li>
      <li>
        <strong>AND</strong>:<br>
        <kbd><em>foo bar</em></kbd> searches for [% terms.bugs %] that contains
        both <kbd>foo</kbd> and <kbd>bar</kbd>.<br>
        <kbd><em>foo AND bar</em></kbd> would have the same effect.
      </li>
      <li>
        <strong>OR</strong>:<br>
        <kbd><em>foo<strong>|</strong>bar</em></kbd> would search
        for [% terms.bugs %] that contain <kbd>foo</kbd> OR <kbd>bar</kbd>.<br>
        <kbd><em>foo OR bar</em></kbd> would have the same effect.<br>
      </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
      (<kbd>url</kbd> OR <kbd>location</kbd>) AND (<kbd>bar</kbd> OR 
      <kbd>field</kbd>) AND (NOT <kbd>focus</kbd>)</p>
  </li>

  <li>
    The default operator, colon (:), performs a <strong>substring</strong>
    match of the value. The following operators are supported:
    <ul>
      <li>
        <strong>:</strong> (substring):<br>
        <kbd><em>summary:foo</em></kbd> will search for [% terms.bugs %]
        where the <kbd>summary</kbd> contains <kbd>foo</kbd>.
      </li>
      <li>
        <strong>=</strong> (equals):<br>
        <kbd><em>summary=foo</em></kbd> will search for [% terms.bugs %]
        where the <kbd>summary</kbd> is exactly <kbd>foo</kbd>.
      </li>
      <li>
        <strong>!=</strong> (notequals):<br>
        <kbd><em>summary!=foo</em></kbd> will search for [% terms.bugs %]
        where the <kbd>summary</kbd> is not <kbd>foo</kbd>.
      </li>
      <li>
        <strong>&gt;</strong> (greaterthan):<br>
        <kbd><em>creation_ts&gt;-2w</em></kbd> will search for [% terms.bugs %]
        where that were created between two weeks ago and now, excluding [%
        terms.bugs %] exactly two weeks old.
      </li>
      <li>
        <strong>&gt;=</strong> (greaterthaneq):<br>
        <kbd><em>creation_ts&gt;=-2w</em></kbd> will search for [% terms.bugs %]
        where that were created between two weeks ago and now, including [%
        terms.bugs %] exactly two weeks old.
      </li>
      <li>
        <strong>&lt;</strong> (lessthan):<br>
        <kbd><em>creation_ts&lt;-2w</em></kbd> will search for [% terms.bugs %]
        where that were created more than two weeks ago, excluding [%
        terms.bugs %] exactly two weeks old.
      </li>
      <li>
        <strong>&lt;=</strong> (lessthaneq):<br>
        <kbd><em>creation_ts&lt;=-2w</em></kbd> will search for [% terms.bugs %]
        where that were created more than two weeks ago, including [%
        terms.bugs %] exactly two weeks old.
      </li>
    </ul>
  </li>
</ul>

<h2 id="shortcuts">Advanced Shortcuts</h2>

<p>In addition to using <a href="#fields">field names</a> to search
  specific fields, there are certain characters or words that you can
  use as a "shortcut" for searching certain fields:</p>

<table cellspacing="0" cellpadding="0" border="0" class="qs_fields">
  <thead>
    <tr>
      <th class="field_name">Field</th>
      <th class="field_nickname">Shortcut(s)</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td class="field_name">[% field_descs.bug_status FILTER html %]</td>
      <td class="field_nickname">
        Make the <strong>first word</strong> of your search the name of any
        status, or even an abbreviation of any status, and [% terms.bugs %]
        in that status will be searched. <strong><kbd>ALL</kbd></strong>
        is a special shortcut that means "all statuses".
        <strong><kbd>OPEN</kbd></strong> is a special shortcut that means
        "all open statuses". Adding a '+' to the end of a status name will
        set the result limit to 0.
      </td>
    </tr>
    <tr>
      <td class="field_name">[% field_descs.resolution FILTER html %]</td>
      <td class="field_nickname">
        Make the <strong>first word</strong> of your search the name of any
        resolution, or even an abbreviation of any resolution, and 
        [%+ terms.bugs %] with that resolution will be searched. For example,
        making <kbd>FIX</kbd> the first word of your search will find all
        [%+ terms.bugs %] with a resolution of <kbd>FIXED</kbd>.
        Adding a '+' to the end of a resolution name will set the result limit
        to 0.
    </tr>
    <tr>
      <td class="field_name">[% field_descs.priority FILTER html %]</td>
      <td class="field_nickname">"<strong>P1</strong>" (as a word anywhere in
        the search) means "find [% terms.bugs %] with the highest priority. 
        "P2" means the second-highest priority, and so on.
        <p>Searching for "<strong>P1-3</strong>" will find [% terms.bugs %] in
        any of the three highest priorities, and so on.</p>
      </td>
    </tr>
    <tr>
      <td class="field_name">[% field_descs.assigned_to FILTER html %]</td>
      <td class="field_nickname"><strong>@</strong><em>value</em></td>
    </tr>
    <tr>
      <td class="field_name">[% field_descs.product FILTER html %] or
        [%+ field_descs.component FILTER html %]</td>
      <td class="field_nickname"><strong>:</strong><em>value</em></td>
    </tr>
    [% IF use_keywords %]
      <tr>
        <td class="field_name">[% field_descs.keywords FILTER html %]</td>
        <td class="field_nickname"><strong>!</strong><em>value</em></td>
      </tr>
    [% END %]
    <tr>
      [% SET key = "flagtypes.name" %]
      <td class="field_name">[% field_descs.$key FILTER html %]</td>
      <td class="field_nickname">
        <em>flag</em><strong>?</strong><em>requestee</em>
      </td>
    </tr>
    <tr>
      <td class="field_name">[% field_descs.longdesc FILTER html %]
        or [% field_descs.short_desc FILTER html %]</td>
      <td class="field_nickname">
        <strong>#</strong><em>value</em>
      </td>
    </tr>
    <tr>
      <td class="field_name">Comment Searching</td>
      <td class="field_nickname">
        Allows overriding of the comment searching preference.<br>
        "<strong>++comments</strong>" will always enable comment searching.<br>
        "<strong>--comments</strong>" will always disable searching.<br>
      </td>
    </tr>
    [% IF Param('usestatuswhiteboard') %]
      <tr>
        <td class="field_name">[% field_descs.short_desc FILTER html %]
          or [% field_descs.status_whiteboard FILTER html %]</td>
        <td class="field_nickname"><strong>[</strong><em>value</em></td>
      </tr>
    [% END %]
  </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 %]