keyword_provider.h revision 731df977c0511bca2206b5f333555b1205ff1f43 
1// Copyright (c) 2010 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 TemplateURLModel to find the set of keywords.
10//
11// For more information on the autocomplete system in general, including how
12// the autocomplete controller and autocomplete providers work, see
13// chrome/browser/autocomplete.h.
14
15#ifndef CHROME_BROWSER_AUTOCOMPLETE_KEYWORD_PROVIDER_H_
16#define CHROME_BROWSER_AUTOCOMPLETE_KEYWORD_PROVIDER_H_
17#pragma once
18
19#include <string>
20
21#include "chrome/browser/autocomplete/autocomplete.h"
22#include "chrome/common/notification_observer.h"
23#include "chrome/common/notification_registrar.h"
24
25class Profile;
26class TemplateURL;
27class TemplateURLModel;
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.
51class KeywordProvider : public AutocompleteProvider,
52                        public NotificationObserver {
53 public:
54  KeywordProvider(ACProviderListener* listener, Profile* profile);
55  // For testing.
56  KeywordProvider(ACProviderListener* listener, TemplateURLModel* model);
57
58  // Returns the replacement string from the user input. The replacement
59  // string is the portion of the input that does not contain the keyword.
60  // For example, the replacement string for "b blah" is blah.
61  static std::wstring SplitReplacementStringFromInput(
62      const std::wstring& input);
63
64  // Returns the matching substituting keyword for |input|, or NULL if there
65  // is no keyword for the specified input.
66  static const TemplateURL* GetSubstitutingTemplateURLForInput(
67      Profile* profile,
68      const AutocompleteInput& input,
69      std::wstring* remaining_input);
70
71  // AutocompleteProvider
72  virtual void Start(const AutocompleteInput& input, bool minimal_changes);
73  virtual void Stop();
74
75 private:
76  class ScopedEndExtensionKeywordMode;
77  friend class ScopedEndExtensionKeywordMode;
78
79  virtual ~KeywordProvider();
80
81  // Extracts the keyword from |input| into |keyword|. Any remaining characters
82  // after the keyword are placed in |remaining_input|. Returns true if |input|
83  // is valid and has a keyword. This makes use of SplitKeywordFromInput to
84  // extract the keyword and remaining string, and uses
85  // TemplateURLModel::CleanUserInputKeyword to remove unnecessary characters.
86  // In general use this instead of SplitKeywordFromInput.
87  static bool ExtractKeywordFromInput(const AutocompleteInput& input,
88                                      std::wstring* keyword,
89                                      std::wstring* remaining_input);
90
91  // Extracts the next whitespace-delimited token from input and returns it.
92  // Sets |remaining_input| to everything after the first token (skipping over
93  // intervening whitespace).
94  static std::wstring SplitKeywordFromInput(const std::wstring& input,
95                                            std::wstring* remaining_input);
96
97  // Fills in the "destination_url" and "contents" fields of |match| with the
98  // provided user input and keyword data.
99  static void FillInURLAndContents(
100      const std::wstring& remaining_input,
101      const TemplateURL* element,
102      AutocompleteMatch* match);
103
104  // Determines the relevance for some input, given its type, whether the user
105  // typed the complete keyword, and whether the keyword needs query text (true
106  // if the keyword supports replacement and the user isn't in "prefer keyword
107  // matches" mode).
108  static int CalculateRelevance(AutocompleteInput::Type type,
109                                bool complete,
110                                bool no_query_text_needed);
111
112  // Creates a fully marked-up AutocompleteMatch from the user's input.
113  // If |relevance| is negative, calculate a relevance based on heuristics.
114  AutocompleteMatch CreateAutocompleteMatch(
115      TemplateURLModel* model,
116      const std::wstring& keyword,
117      const AutocompleteInput& input,
118      size_t prefix_length,
119      const std::wstring& remaining_input,
120      int relevance);
121
122  void EnterExtensionKeywordMode(const std::string& extension_id);
123  void MaybeEndExtensionKeywordMode();
124
125  // NotificationObserver interface.
126  void Observe(NotificationType type,
127               const NotificationSource& source,
128               const NotificationDetails& details);
129
130  // Model for the keywords.  This is only non-null when testing, otherwise the
131  // TemplateURLModel from the Profile is used.
132  TemplateURLModel* model_;
133
134  // Identifies the current input state. This is incremented each time the
135  // autocomplete edit's input changes in any way. It is used to tell whether
136  // suggest results from the extension are current.
137  int current_input_id_;
138
139  // The input state at the time we last asked the extension for suggest
140  // results.
141  AutocompleteInput extension_suggest_last_input_;
142
143  // We remember the last suggestions we've received from the extension in case
144  // we need to reset our matches without asking the extension again.
145  std::vector<AutocompleteMatch> extension_suggest_matches_;
146
147  // If non-empty, holds the ID of the extension whose keyword is currently in
148  // the URL bar while the autocomplete popup is open.
149  std::string current_keyword_extension_id_;
150
151  NotificationRegistrar registrar_;
152
153  DISALLOW_COPY_AND_ASSIGN(KeywordProvider);
154};
155
156#endif  // CHROME_BROWSER_AUTOCOMPLETE_KEYWORD_PROVIDER_H_
157