components/omnibox/keyword_provider.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5 // This file contains the keyword autocomplete provider. The keyword provider
   6 // is responsible for remembering/suggesting user "search keyword queries"
   7 // (e.g.  "imdb Godzilla") and then fixing them up into valid URLs.  An
   8 // instance of it gets created and managed by the autocomplete controller.
   9 // KeywordProvider uses a TemplateURLService to find the set of keywords.
  10
  11 #ifndef COMPONENTS_OMNIBOX_KEYWORD_PROVIDER_H_
  12 #define COMPONENTS_OMNIBOX_KEYWORD_PROVIDER_H_
  13
  14 #include <string>
  15
  16 #include "base/basictypes.h"
  17 #include "base/compiler_specific.h"
  18 #include "base/memory/scoped_ptr.h"
  19 #include "components/metrics/proto/omnibox_input_type.pb.h"
  20 #include "components/omnibox/autocomplete_input.h"
  21 #include "components/omnibox/autocomplete_provider.h"
  22 #include "components/omnibox/keyword_extensions_delegate.h"
  23
  24 class AutocompleteProviderListener;
  25 class KeywordExtensionsDelegate;
  26 class TemplateURL;
  27 class TemplateURLService;
  28
  29 // Autocomplete provider for keyword input.
  30 //
  31 // After construction, the autocomplete controller repeatedly calls Start()
  32 // with some user input, each time expecting to receive a small set of the best
  33 // matches (either synchronously or asynchronously).
  34 //
  35 // To construct these matches, the provider treats user input as a series of
  36 // whitespace-delimited tokens and tries to match the first token as the prefix
  37 // of a known "keyword".  A keyword is some string that maps to a search query
  38 // URL; the rest of the user's input is taken as the input to the query.  For
  39 // example, the keyword "bug" might map to the URL "http://b/issue?id=%s", so
  40 // input like "bug 123" would become "http://b/issue?id=123".
  41 //
  42 // Because we do prefix matching, user input could match more than one keyword
  43 // at once.  (Example: the input "f jazz" matches all keywords starting with
  44 // "f".)  We return the best matches, up to three.
  45 //
  46 // The resulting matches are shown with content specified by the keyword
  47 // (usually "Search [name] for %s"), description "(Keyword: [keyword])", and
  48 // action "[keyword] %s".  If the user has typed a (possibly partial) keyword
  49 // but no search terms, the suggested result is shown greyed out, with
  50 // "<enter term(s)>" as the substituted input, and does nothing when selected.
  51 class KeywordProvider : public AutocompleteProvider {
  52  public:
  53   KeywordProvider(AutocompleteProviderListener* listener,
  54                   TemplateURLService* model);
  55
  56   void set_extensions_delegate(
  57       scoped_ptr<KeywordExtensionsDelegate> extensions_delegate) {
  58     extensions_delegate_ = extensions_delegate.Pass();
  59   }
  60
  61   // Extracts the next whitespace-delimited token from input and returns it.
  62   // Sets |remaining_input| to everything after the first token (skipping over
  63   // the first intervening whitespace).
  64   // If |trim_leading_whitespace| is true then leading whitespace in
  65   // |*remaining_input| will be trimmed.
  66   static base::string16 SplitKeywordFromInput(const base::string16& input,
  67                                               bool trim_leading_whitespace,
  68                                               base::string16* remaining_input);
  69
  70   // Returns the replacement string from the user input. The replacement
  71   // string is the portion of the input that does not contain the keyword.
  72   // For example, the replacement string for "b blah" is blah.
  73   // If |trim_leading_whitespace| is true then leading whitespace in
  74   // replacement string will be trimmed.
  75   static base::string16 SplitReplacementStringFromInput(
  76       const base::string16& input,
  77       bool trim_leading_whitespace);
  78
  79   // Returns the matching substituting keyword for |input|, or NULL if there
  80   // is no keyword for the specified input.  If the matching keyword was found,
  81   // updates |input|'s text and cursor position.
  82   static const TemplateURL* GetSubstitutingTemplateURLForInput(
  83       TemplateURLService* model,
  84       AutocompleteInput* input);
  85
  86   // If |text| corresponds (in the sense of
  87   // TemplateURLModel::CleanUserInputKeyword()) to an enabled, substituting
  88   // keyword, returns that keyword; returns the empty string otherwise.
  89   base::string16 GetKeywordForText(const base::string16& text) const;
  90
  91   // Creates a fully marked-up AutocompleteMatch for a specific keyword.
  92   AutocompleteMatch CreateVerbatimMatch(const base::string16& text,
  93                                         const base::string16& keyword,
  94                                         const AutocompleteInput& input);
  95
  96   // AutocompleteProvider:
  97   void Start(const AutocompleteInput& input,
  98              bool minimal_changes,
  99              bool called_due_to_focus) override;
 100   void Stop(bool clear_cached_results) override;
 101
 102  private:
 103   friend class KeywordExtensionsDelegateImpl;
 104
 105   ~KeywordProvider() override;
 106
 107   // Extracts the keyword from |input| into |keyword|. Any remaining characters
 108   // after the keyword are placed in |remaining_input|. Returns true if |input|
 109   // is valid and has a keyword. This makes use of SplitKeywordFromInput to
 110   // extract the keyword and remaining string, and uses
 111   // TemplateURLService::CleanUserInputKeyword to remove unnecessary characters.
 112   // In general use this instead of SplitKeywordFromInput.
 113   // Leading whitespace in |*remaining_input| will be trimmed.
 114   static bool ExtractKeywordFromInput(const AutocompleteInput& input,
 115                                       base::string16* keyword,
 116                                       base::string16* remaining_input);
 117
 118   // Determines the relevance for some input, given its type, whether the user
 119   // typed the complete keyword, and whether the user is in "prefer keyword
 120   // matches" mode, and whether the keyword supports replacement.
 121   // If |allow_exact_keyword_match| is false, the relevance for complete
 122   // keywords that support replacements is degraded.
 123   static int CalculateRelevance(metrics::OmniboxInputType::Type type,
 124                                 bool complete,
 125                                 bool support_replacement,
 126                                 bool prefer_keyword,
 127                                 bool allow_exact_keyword_match);
 128
 129   // Creates a fully marked-up AutocompleteMatch from the user's input.
 130   // If |relevance| is negative, calculate a relevance based on heuristics.
 131   AutocompleteMatch CreateAutocompleteMatch(
 132       const TemplateURL* template_url,
 133       const AutocompleteInput& input,
 134       size_t prefix_length,
 135       const base::string16& remaining_input,
 136       bool allowed_to_be_default_match,
 137       int relevance);
 138
 139   // Fills in the "destination_url" and "contents" fields of |match| with the
 140   // provided user input and keyword data.
 141   void FillInURLAndContents(const base::string16& remaining_input,
 142                             const TemplateURL* element,
 143                             AutocompleteMatch* match) const;
 144
 145   TemplateURLService* GetTemplateURLService() const;
 146
 147   AutocompleteProviderListener* listener_;
 148
 149   // Model for the keywords.
 150   TemplateURLService* model_;
 151
 152   // Delegate to handle the extensions-only logic for KeywordProvider.
 153   // NULL when extensions are not enabled. May be NULL for tests.
 154   scoped_ptr<KeywordExtensionsDelegate> extensions_delegate_;
 155
 156   DISALLOW_COPY_AND_ASSIGN(KeywordProvider);
 157 };
 158
 159 #endif  // COMPONENTS_OMNIBOX_KEYWORD_PROVIDER_H_