From 7f85d8e57d72ce68752cbf78bc633f00ee8da29a Mon Sep 17 00:00:00 2001 From: Max Kanat-Alexander Date: Sun, 7 Feb 2010 15:35:30 -0800 Subject: Bug 518293: Improve and Simplify the QuickSearch Documentation r=LpSolit, a=LpSolit --- template/en/default/pages/quicksearch.html.tmpl | 362 +++++++++++++++--------- 1 file changed, 223 insertions(+), 139 deletions(-) (limited to 'template/en/default/pages/quicksearch.html.tmpl') diff --git a/template/en/default/pages/quicksearch.html.tmpl b/template/en/default/pages/quicksearch.html.tmpl index 3fd7c45b9..93b0f5910 100644 --- a/template/en/default/pages/quicksearch.html.tmpl +++ b/template/en/default/pages/quicksearch.html.tmpl @@ -10,29 +10,25 @@ # # The Original Code is the Bugzilla Bug Tracking System. # - # Contributor(s): N.N. - # Marc Schumann + # 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 #%] -[% PROCESS global/variables.none.tmpl %] +[% PROCESS "global/field-descs.none.tmpl" %] [% INCLUDE global/header.html.tmpl title = "$terms.Bugzilla QuickSearch", - style = 'ul {margin-bottom: 2ex} - ul li {margin-top: 2ex} - ul li ul li {margin-top: 0}' + style_urls = ['skins/standard/page.css'] onload = 'document.forms[\'f\'].quicksearch.focus()' %] -

- If you are already familiar with the original - [% terms.Bugzilla %] Search Form, - you may prefer this form. -

+[% USE Bugzilla %] -

- Type in one or more words (or word fragments) to search for: -

+

Type in one or more words (or pieces of words) to search for:

-

Getting Started

+

The Basics

-
    -
  • - This is case-insensitive search:
    -
      -
    • table, Table and TABLE are all the same.
      • -
    -
    • -
  • - This is all words as substrings - search.
    - Therefore you should use stems to get better results: -
      -
    • - Use localiz instead of localize or - localization. -
      • -
    • - Use bookmark instead of bookmarks or - bookmarking. -
      • -
    +
      +
    • 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 %] + [%+ 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.
      • + +
    • Typing just a number in the search box will take + you directly to the [% terms.bug %] with that ID. + [% IF Param('usebugaliases') %] + Also, just typing the alias of [% terms.abug %] + will take you to that [% terms.bug %]. + [% END %]
      • + +
    • Adding more terms narrows down the search, it does not + expand it. (In other words, [% terms.Bugzilla %] searches for + [%+ terms.bugs %] that match all your criteria, not + [%+ terms.bugs %] that match any of your criteria.)
      • + +
    • Searching is case-insensitive. So table, + Table, and TABLE are all the same.
      • + +
    • [% terms.Bugzilla %] does not just search for the exact word you put in, + but also for any word that contains that word. + So, for example, searching for "cat" would also find [% terms.bugs %] + that contain it—for example, a but mentioning + "catch" or "certificate". It will + not find partial words in the [% field_descs.longdesc FILTER html %] + or [% field_descs.keywords FILTER html %] fields, + though—only full words are matched, there.
      • + +
    • By default, only open [% terms.bugs %] are + searched. If you want to know how to also search closed [% terms.bugs %], + see the Advanced Shortcuts section.
      • + +
    • If you want to search specific fields, you do it like + field:value, where field is one of the + field names lower down in this + document, and value is the value you want to search for + in that field. If put commas in the value, then it is + interpreted as a list of values, and [% terms.bugs %] that match + any of those values will be searched for.
    -

    Features

    +

    You may also want to read up on the Advanced + Features.

    -
      -
    • - Boolean operations: “-foo” (NOT), - “foo bar” (AND), - “foo|bar” (OR). -
        -
      • - NOT:
        - Use -foo to exclude [% terms.bugs %] - with foo in the summary. -
        • -
      • - AND:
        - Space-separated words are treated as a conjunction. -
        • -
      • - OR:
        - Within a word, "|"-separated parts denote alternatives. -
        • -
      • - Besides "|", a comma can be used to separate alternatives. -
        • -
      • - OR has higher precedence than AND; AND is the top level operation. -
        • -
      - Example: - url,location bar,field -focus means - (url OR location) AND (bar OR field) - AND (NOT focus) -
      • -
    • - Use +foo to search for [% terms.bugs %] where the - summary contains foo as a - substring.
      - Use #foo to search for [% terms.bugs %] where the - summary contains the word foo. -
        -
      • - +brow does not find all [% terms.bugs %] in the - Browser product. -
        • -
      • - #title does not find [% terms.bugs %] with titlebar - or titled. -
        • -
      - Phrases with special chars (space, comma, +, -, #, …) can be - quoted: +

      Fields You Can Search On

      + +

      You can specify any of these fields like field:value + 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 stat:NEW will find all + [%+ terms.bugs %] in the NEW status. Some fields have + multiple names, and you can use any of those names to search for them.

      + +[% IF Bugzilla.active_custom_fields.size %] + [% SET first_field = Bugzilla.active_custom_fields.0 %] +

      For custom fields, they can be used and abbreviated + based on the part of their name after the cf_ + if you'd like, in addition to their standard name starting with + cf_. So for example, + [% first_field.name FILTER html %] can be + referred to as + [% first_field.name.replace('^cf_') FILTER html %], + 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.

      +[% END %] + +[% SET field_table = {} %] +[% FOREACH field = quicksearch_field_names.keys %] + [% description = field_descs.$field %] + [% field_table.$description = quicksearch_field_names.${field} %] +[% END %] + + + + + + + + + + + [% FOREACH desc = field_table.keys.sort %] + + + + [% END %] + +
      FieldField Name(s) For Search
      [% desc FILTER html %] + [% FOREACH nickname = field_table.$desc %] + [% nickname FILTER html %] + [% ",  " UNLESS loop.last %] + [% END %] +
      + +

      Advanced Features

      + +
        +
      • If you want to search for a phrase or something that + contains spaces, you can put it in quotes, like: + "this is a phrase". You can also use quotes to search for + characters that would otherwise be interpreted specially by quicksearch. + For example, "this|thing" would search for the literal phrase + this|thing.
        • + +
      • You can use AND, NOT, + and OR in searches. + + You can also use - to mean "NOT", and | 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:
        • - "lock icon" + NOT:
          + Use -summary:foo to exclude + [%+ terms.bugs %] with foo in the summary.
          + NOT summary:foo would have the same effect.
          • -
        -
        • -
      • - Open vs. Resolved [% terms.Bugs %]:
        - By default, only open (i.e. unresolved) [% terms.bugs %] are shown. - Use +DUP as first word in your search to include duplicate - [%+ terms.bugs %] in your search, - FIXED to search for fixed [%+ terms.bugs %] only, - or ALL to search all [% terms.bugs %], - regardless of status or resolution. - Searching for duplicates is recommended if you can't find an open - [%+ terms.bug %] directly. -
        • - +DUP,FIXED table border + AND:
          + foo bar searches for [% terms.bugs %] that contains + both foo and bar.
          + foo AND bar would have the same effect.
        • - ALL mouse wheel + OR:
          + foo|bar would search + for [% terms.bugs %] that contain foo OR bar.
          + foo OR bar would have the same effect.
        -
        • -
      • - Focus the Search with Products & - Components:
        - To search for [% terms.bugs %] in product "Foo Bar" only, add - :foo or :bar or both to your search. - You can do this with any substring of a - product or component to focus the - search. + +

        OR has higher precedence than AND; AND is the top level operation. + For example:

        +

        Searching for url|location bar|field -focus means + (url OR location) AND (bar OR + field) AND (NOT focus)

      -

      More Tips

      +

      Advanced Shortcuts

      -
        -
      • - You can also use this tool to lookup a [% terms.bug %] by - its number:
        -
          -
        • 12345
          • -
        -
        • -
      • - A comma-separated list of [% terms.bug %] numbers gives you a list of these - [%+ terms.bugs %]:
        -
          -
        • 12345,23456,34567
          • -
        -
        • -
      +

      In addition to using field names to search + specific fields, there are certain characters or words that you can + use as a "shortcut" for searching certain fields:

      -

      - By default, the following fields are searched: Summary, Keywords, Product, - Component, Status Whiteboard. If a word looks like a part of a URL, that field - is included in the search, too. -

      -
      - -

      - Use the powerful [% terms.Bugzilla %] Search Form - for advanced queries. -

      + + + + + + + + + + + + + + + + + + + + + + + + + + + + [% IF use_keywords %] + + + + + [% END %] + + [% SET key = "flagtypes.name" %] + + + + + + + + [% IF Param('usestatuswhiteboard') %] + + + + + [% END %] + +
      FieldShortcut(s)
      [% field_descs.bug_status FILTER html %] + Make the first word of your search the name of any + status, or even an abbreviation of any status, and [% terms.bugs %] + in that status will be searched. ALL + is a special shortcut that means "all statuses". + OPEN is a special shortcut that means + "all open statuses". +
      [% field_descs.resolution FILTER html %] + Make the first word 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 FIX the first word of your search will find all + [%+ terms.bugs %] with a resolution of FIXED . +
      [% field_descs.priority FILTER html %]"P1" (as a word anywhere in + the search) means "find [% terms.bugs %] with the highest priority. + "P2" means the second-highest priority, and so on. +

      Searching for "P1-P3" will find [% terms.bugs %] in + any of the three highest priorities, and so on.

      +
      [% field_descs.assigned_to FILTER html %]@value
      [% field_descs.product FILTER html %] or + [%+ field_descs.component FILTER html %]:value
      [% field_descs.keywords FILTER html %]!value
      [% field_descs.$key FILTER html %] + flag?requestee +
      [% field_descs.longdesc FILTER html %] + or [% field_descs.short_desc FILTER html %] + #value +
      [% field_descs.short_desc FILTER html %] + or [% field_descs.status_whiteboard FILTER html %][value
      [% PROCESS global/footer.html.tmpl %] -- cgit v1.2.3-24-g4f1b