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 --- .bzrignore | 2 +- page.cgi | 27 +- skins/standard/page.css | 70 ++++ skins/standard/release-notes.css | 35 -- template/en/default/global/common-links.html.tmpl | 3 +- template/en/default/global/user-error.html.tmpl | 4 +- template/en/default/pages/quicksearch.html.tmpl | 362 +++++++++++-------- .../en/default/pages/quicksearchhack.html.tmpl | 387 --------------------- template/en/default/pages/release-notes.html.tmpl | 2 +- 9 files changed, 325 insertions(+), 567 deletions(-) create mode 100644 skins/standard/page.css delete mode 100644 skins/standard/release-notes.css delete mode 100644 template/en/default/pages/quicksearchhack.html.tmpl diff --git a/.bzrignore b/.bzrignore index 0a247ff2b..e42398ecc 100644 --- a/.bzrignore +++ b/.bzrignore @@ -21,8 +21,8 @@ /skins/contrib/Dusk/editusers.css /skins/contrib/Dusk/help.css /skins/contrib/Dusk/panel.css +/skins/contrib/Dusk/page.css /skins/contrib/Dusk/params.css -/skins/contrib/Dusk/release-notes.css /skins/contrib/Dusk/reports.css /skins/contrib/Dusk/show_bug.css /skins/contrib/Dusk/show_multiple.css diff --git a/page.cgi b/page.cgi index d889841b3..cd6cb611e 100755 --- a/page.cgi +++ b/page.cgi @@ -35,6 +35,29 @@ use lib qw(. lib); use Bugzilla; use Bugzilla::Error; use Bugzilla::Hook; +use Bugzilla::Search::Quicksearch; + +############### +# Subroutines # +############### + +# For quicksearch.html. +sub quicksearch_field_names { + my $fields = Bugzilla::Search::Quicksearch::FIELD_MAP; + my %fields_reverse; + # Put longer names before shorter names. + my @nicknames = sort { length($b) <=> length($a) } (keys %$fields); + foreach my $nickname (@nicknames) { + my $db_field = $fields->{$nickname}; + $fields_reverse{$db_field} ||= []; + push(@{ $fields_reverse{$db_field} }, $nickname); + } + return \%fields_reverse; +} + +############### +# Main Script # +############### Bugzilla->login(); @@ -51,7 +74,9 @@ if ($id) { ThrowCodeError("bad_page_cgi_id", { "page_id" => $id }); } - my %vars; + my %vars = ( + quicksearch_field_names => \&quicksearch_field_names, + ); Bugzilla::Hook::process('page_before_template', { page_id => $id, vars => \%vars }); diff --git a/skins/standard/page.css b/skins/standard/page.css new file mode 100644 index 000000000..47869bb58 --- /dev/null +++ b/skins/standard/page.css @@ -0,0 +1,70 @@ +/* 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 Initial Developer of the Original Code is Everything Solved. + * Portions created by Everything Solved are Copyright (C) 2006 + * Everything Solved. All Rights Reserved. + * + * The Original Code is the Bugzilla Bug Tracking System. + * + * Contributor(s): Max Kanat-Alexander + */ + +/* This CSS is used by various informational pages in the + template/en/default/pages/ directory. */ + +#bugzilla-body { + padding: 0 1em; +} + +#bugzilla-body > * { + /* People have an easier time reading narrower columns of text. */ + max-width: 45em; +} + +/*****************/ +/* Release Notes */ +/*****************/ + +.req_new { + color: red; +} + +.req_table { + border-collapse: collapse; +} + +.req_table td, .req_table th { + border: 1px solid black; + padding: .25em; +} + +/********************/ +/* QuickSearch Help */ +/********************/ + +.qs_help li { + margin-top: 1ex; +} + +.qs_fields th { + padding: 0 .25em; +} +.qs_fields th.field_nickname { + text-align: left; +} +.qs_fields td { + padding: .25em; + border-top: 1px solid gray; +} +.qs_fields .field_name { + width: 10em; +} + diff --git a/skins/standard/release-notes.css b/skins/standard/release-notes.css deleted file mode 100644 index 51159ae20..000000000 --- a/skins/standard/release-notes.css +++ /dev/null @@ -1,35 +0,0 @@ -/* 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 Initial Developer of the Original Code is Everything Solved. - * Portions created by Everything Solved are Copyright (C) 2006 - * Everything Solved. All Rights Reserved. - * - * The Original Code is the Bugzilla Bug Tracking System. - * - * Contributor(s): Max Kanat-Alexander - */ - -#bugzilla-body { - padding: 0 1em; -} - -.req_new { - color: red; -} - -.req_table { - border-collapse: collapse; -} - -.req_table td, .req_table th { - border: 1px solid black; - padding: .25em; -} diff --git a/template/en/default/global/common-links.html.tmpl b/template/en/default/global/common-links.html.tmpl index 70395b319..6ad638f72 100644 --- a/template/en/default/global/common-links.html.tmpl +++ b/template/en/default/global/common-links.html.tmpl @@ -37,7 +37,8 @@ - [%-# Work around FF bug: keep this on one line %] + [%-# Work around FF bug: keep this on one line %] + [?]
  • | Reports
    • diff --git a/template/en/default/global/user-error.html.tmpl b/template/en/default/global/user-error.html.tmpl index 37429a57d..eca7ef058 100644 --- a/template/en/default/global/user-error.html.tmpl +++ b/template/en/default/global/user-error.html.tmpl @@ -1436,8 +1436,8 @@ [% END %] [% IF unknown.size %] -

    The legal field names are - listed here.

    +

    The legal field names are + listed here.

    [% END %] [% ELSIF error == "reassign_to_empty" %] 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 %] diff --git a/template/en/default/pages/quicksearchhack.html.tmpl b/template/en/default/pages/quicksearchhack.html.tmpl deleted file mode 100644 index 06f8c6dbd..000000000 --- a/template/en/default/pages/quicksearchhack.html.tmpl +++ /dev/null @@ -1,387 +0,0 @@ -[%# 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. - # - # Contributor(s): N.N. - # Marc Schumann - #%] - -[% PROCESS global/variables.none.tmpl %] - -[% INCLUDE global/header.html.tmpl - title = "$terms.Bugzilla QuickSearch (for Hackers)", - style = 'th {text-align: left}' - onload = 'document.forms[\'f\'].quicksearch.focus()' - %] - -

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

        - -
        - - - -
        - -

        - This is a case-insensitive “all words as substrings” search; - words are separated by spaces. - By default, the following fields are relevant: Summary, Keywords, - Product, Component, Status Whiteboard. - If a word looks like a part of a URL, that field is included in the search, - too. -

        -

        - The generic format for a “word” is - field1,…,fieldN:value1,…,valueM. - A [% terms.bug %] qualifies if at least one of the values occurs as a - substring in at least one of the fields. - For example, assignee,reporter,qa:ibm,sun will give you - [%+ terms.bugs %] where the assignee, reporter, or qa contact has a login - that contains ibm or sun. - If only value1,…,valueM is given, the prefix (roughly) defaults to - summary,keywords,product,component,statuswhiteboard: as noted above. - You can use -word to express the logical negation of - word. -

        -

        - Here is a complete listing of available fields (the Shortcut column is just - for access speed): -

        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        Searched by defaultShortcutField NameAliasesDescription
          - UNCO,NEW,…,CLOS,
        FIX,DUP,…(as first word)         -         		status  - Status - (“bug_status”) -
         resolution Resolution
         as-isplatform  - Platform - (“rep_platform”) -
          osopsys - OS - (“op_sys”) -
         p1,p2 or p1-2prioritypriPriority
         blo,cri,…,enhseveritysev - Severity - (“bug_severity”) -
         @assigneeassignedtoassignee - Assignee - (“assigned_to”) -
          reporterrepReporter (login)
          qaqacontactQA Contact (login) (“qa_contact”)
          cc CC (login)
        yes:areaproductprodProduct (enum)
        yescomponentcompComponent
          versionverVersion (enum)
          milestonetarget, targetmilestoneTarget Milestone (“target_milestone”)
        yes summaryshortdesc - [% terms.Bug %] Summary (short text) - (“short_desc”) -
          descriptiondesc, longdesc[% terms.Bug %] Description / Comments (long text)
        depends url URL (“bug_file_loc”)
        yes statuswhiteboardsw, whiteboardStatus Whiteboard (“status_whiteboard”)
        yes!keywordkeywordskwKeywords
          group Group
         flag?requesteeflag Flag name and status (+, - or ?)
         requesteereqFlag requestee (login)
          settersetFlag setter (login)
          attachmentdescattachdesc - Attachment Description - (“attachments.description”) -
          attachmentdataattachdataAttachment Data (“attach_data.thedata”)
          attachmentmimetypeattachmimetypeAttachment mime-type (“attachments.mimetype”)
          votes  - Number of votes
        - (votes:N and votes>=N mean "at least N votes", - votes>N means "more than N votes") -
        - -

        - Examples for some useful abbreviations: -

        - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
        SyntaxSemantics and Examples
        :areaproduct,component:area
        sevseverity:sev
        blo,cri,majsevere [% terms.bugs %]
        enhenhancement requests
        plevelpriority:level
        p1very high-priority [% terms.bugs %]
        p1-2high-priority [% terms.bugs %]
        @assigneeassignedto:assignee
        !keywordkeywords:keyword
        flag?requesteeflag:flag? requestee:requestee
        - -

        - More information can be found in the - “Features” - section on the introductory page. -

        - -[% PROCESS global/footer.html.tmpl %] diff --git a/template/en/default/pages/release-notes.html.tmpl b/template/en/default/pages/release-notes.html.tmpl index 35d586bde..4156ce03b 100644 --- a/template/en/default/pages/release-notes.html.tmpl +++ b/template/en/default/pages/release-notes.html.tmpl @@ -20,7 +20,7 @@ [% PROCESS global/variables.none.tmpl %] [% INCLUDE global/header.html.tmpl title = "$terms.Bugzilla 3.4 Release Notes" - style_urls = ['skins/standard/release-notes.css'] + style_urls = ['skins/standard/page.css'] %]

        Table of Contents

        -- cgit v1.2.3-24-g4f1b