1 // Copyright (c) 2006-2008 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.
5 #ifndef CHROME_BROWSER_TEMPLATE_URL_H__
6 #define CHROME_BROWSER_TEMPLATE_URL_H__
10 #include "base/basictypes.h"
11 #include "base/time.h"
12 #include "googleurl/src/gurl.h"
16 // TemplateURL represents the relevant portions of the Open Search Description
17 // Document (http://www.opensearch.org/Specifications/OpenSearch).
18 // The main use case for TemplateURL is to use the TemplateURLRef returned by
19 // suggestions_url or url for keyword/suggestion expansion:
20 // . suggestions_url describes a URL that is ideal for as you type suggestions.
21 // The returned results are in the mime type application/x-suggestions+json.
22 // . url describes a URL that may be used as a shortcut. Returned results are
24 // Before using either one, make sure it's non-NULL, and if you intend to use
25 // it to replace search terms, make sure SupportsReplacement returns true.
26 // To use either URL invoke the ReplaceSearchTerms method on the corresponding
29 // For files parsed from the Web, be sure and invoke IsValid. IsValid returns
30 // true if the URL could be parsed.
32 // Both TemplateURL and TemplateURLRef have value semantics. This allows the
33 // UI to create a copy while the user modifies the values.
34 class TemplateURLRef
{
36 // Magic numbers to pass to ReplaceSearchTerms() for the |accepted_suggestion|
37 // parameter. Most callers aren't using Suggest capabilities and should just
38 // pass NO_SUGGESTIONS_AVAILABLE.
39 // NOTE: Because positive values are meaningful, make sure these are negative!
40 enum AcceptedSuggestion
{
41 NO_SUGGESTION_CHOSEN
= -1,
42 NO_SUGGESTIONS_AVAILABLE
= -2,
47 TemplateURLRef(const std::wstring
& url
, int index_offset
, int page_offset
)
49 index_offset_(index_offset
),
50 page_offset_(page_offset
),
53 supports_replacements_(false) {
56 // Returns true if this URL supports replacement.
57 bool SupportsReplacement() const;
59 // Returns a string that is the result of replacing the search terms in
60 // the url with the specified value.
62 // If this TemplateURLRef does not support replacement (SupportsReplacement
63 // returns false), an empty string is returned.
65 // The TemplateURL is used to determine the input encoding for the term.
66 std::wstring
ReplaceSearchTerms(
67 const TemplateURL
& host
,
68 const std::wstring
& terms
,
69 int accepted_suggestion
,
70 const std::wstring
& original_query_for_suggestion
) const;
72 // Returns the raw URL. None of the parameters will have been replaced.
73 const std::wstring
& url() const { return url_
; }
75 // Returns the index number of the first search result.
76 int index_offset() const { return index_offset_
; }
78 // Returns the page number of the first search results.
79 int page_offset() const { return page_offset_
; }
81 // Returns true if the TemplateURLRef is valid. An invalid TemplateURLRef is
82 // one that contains unknown terms, or invalid characters.
85 // Returns a string representation of this TemplateURLRef suitable for
86 // display. The display format is the same as the format used by Firefox.
87 std::wstring
DisplayURL() const;
89 // Converts a string as returned by DisplayURL back into a string as
90 // understood by TemplateURLRef.
91 static std::wstring
DisplayURLToURLRef(const std::wstring
& display_url
);
93 // If this TemplateURLRef is valid and contains one search term, this returns
94 // the host/path of the URL, otherwise this returns an empty string.
95 const std::string
& GetHost() const;
96 const std::string
& GetPath() const;
98 // If this TemplateURLRef is valid and contains one search term, this returns
99 // the key of the search term, otherwise this returns an empty string.
100 const std::string
& GetSearchTermKey() const;
102 // Converts the specified term in the encoding of the host TemplateURL to a
104 std::wstring
SearchTermToWide(const TemplateURL
& host
,
105 const std::string
& term
) const;
107 // Returns true if this TemplateURLRef has a replacement term of
108 // {google:baseURL} or {google:baseSuggestURL}.
109 bool HasGoogleBaseURLs() const;
112 friend class TemplateURL
;
113 friend class TemplateURLModelTest
;
114 friend class TemplateURLTest
;
116 // Enumeration of the known types.
117 enum ReplacementType
{
119 GOOGLE_ACCEPTED_SUGGESTION
,
121 GOOGLE_BASE_SUGGEST_URL
,
122 GOOGLE_ORIGINAL_QUERY_FOR_SUGGESTION
,
124 GOOGLE_UNESCAPED_SEARCH_TERMS
,
129 // Used to identify an element of the raw url that can be replaced.
131 Replacement(ReplacementType type
, int index
) : type(type
), index(index
) {}
132 ReplacementType type
;
136 // The list of elements to replace.
137 typedef std::vector
<struct Replacement
> Replacements
;
139 // TemplateURLRef internally caches values to make replacement quick. This
140 // method invalidates any cached values.
141 void InvalidateCachedValues() const;
144 void Set(const std::wstring
& url
, int index_offset
, int page_offset
);
146 // Parses the parameter in url at the specified offset. start/end specify the
147 // range of the parameter in the url, including the braces. If the parameter
148 // is valid, url is updated to reflect the appropriate parameter. If
149 // the parameter is one of the known parameters an element is added to
150 // replacements indicating the type and range of the element.
152 // If the parameter is not a known parameter, false is returned.
153 bool ParseParameter(size_t start
,
156 Replacements
* replacements
) const;
158 // Parses the specified url, replacing parameters as necessary. If
159 // successful, valid is set to true, and the parsed url is returned. For all
160 // known parameters that are encountered an entry is added to replacements.
161 // If there is an error parsing (unknown parameter, or bogus url), valid is
162 // set to false, and an empty string is returned.
163 std::wstring
ParseURL(const std::wstring
& url
,
164 Replacements
* replacements
,
167 // If the url has not yet been parsed, ParseURL is invoked.
168 // NOTE: While this is const, it modifies parsed_, valid_, parsed_url_ and
170 void ParseIfNecessary() const;
172 // Extracts the query key and host from the url.
173 void ParseHostAndSearchTermKey() const;
175 // Returns the value for the GOOGLE_BASE_URL term.
176 static std::wstring
GoogleBaseURLValue();
178 // Returns the value for the GOOGLE_BASE_SUGGEST_URL term.
179 static std::wstring
GoogleBaseSuggestURLValue();
181 // The raw URL. Where as this contains all the terms (such as {searchTerms}),
182 // parsed_url_ has them all stripped out.
185 // indexOffset defined for the Url element.
188 // searchOffset defined for the Url element.
191 // Whether the URL has been parsed.
192 mutable bool parsed_
;
194 // Whether the url was successfully parsed.
197 // The parsed URL. All terms have been stripped out of this with
198 // replacements_ giving the index of the terms to replace.
199 mutable std::wstring parsed_url_
;
201 // Do we support replacement?
202 mutable bool supports_replacements_
;
204 // The replaceable parts of url (parsed_url_). These are ordered by index
205 // into the string, and may be empty.
206 mutable Replacements replacements_
;
208 // Host, path and key of the search term. These are only set if the url
209 // contains one search term.
210 mutable std::string host_
;
211 mutable std::string path_
;
212 mutable std::string search_term_key_
;
214 // For testing. If non-null this is the replacement value for GOOGLE_BASE_URL
216 static std::wstring
* google_base_url_
;
219 // Describes the relevant portions of a single OSD document.
222 typedef int64 IDType
;
224 // Describes a single image reference. Each TemplateURL may have
225 // any number (including 0) of ImageRefs.
227 // If a TemplateURL has no images, the favicon for the generated URL
230 ImageRef(const std::wstring
& type
, int width
, int height
)
231 : type(type
), width(width
), height(height
) {
234 ImageRef(const std::wstring
& type
, int width
, int height
, const GURL
& url
)
235 : type(type
), width(width
), height(height
), url(url
) {
238 // Mime type for the image.
239 // ICO image will have the format: image/x-icon or image/vnd.microsoft.icon
250 // Generates a favicon URL from the specified url.
251 static GURL
GenerateFaviconURL(const GURL
& url
);
254 : autogenerate_keyword_(false),
255 show_in_default_list_(false),
256 safe_for_autoreplace_(false),
258 date_created_(Time::Now()),
260 prepopulate_id_(0) {}
263 // A short description of the template. This is the name we show to the user
264 // in various places that use keywords. For example, the location bar shows
265 // this when the user selects the keyword.
266 void set_short_name(const std::wstring
& short_name
) {
267 short_name_
= short_name
;
269 const std::wstring
& short_name() const { return short_name_
; }
271 // A description of the template; this may be empty.
272 void set_description(const std::wstring
& description
) {
273 description_
= description
;
275 const std::wstring
& description() const { return description_
; }
277 // URL providing JSON results. This is typically used to provide suggestions
278 // as your type. If NULL, this url does not support suggestions.
279 // Be sure and check the resulting TemplateURLRef for SupportsReplacement
281 void SetSuggestionsURL(const std::wstring
& suggestions_url
,
284 const TemplateURLRef
* suggestions_url() const {
285 if (suggestions_url_
.url().empty())
287 return &suggestions_url_
;
290 // Parameterized URL for providing the results. This may be NULL.
291 // Be sure and check the resulting TemplateURLRef for SupportsReplacement
293 void SetURL(const std::wstring
& url
, int index_offset
, int page_offset
);
294 // Returns the TemplateURLRef that may be used for search results. This
295 // returns NULL if a url element was not specified.
296 const TemplateURLRef
* url() const {
297 if (url_
.url().empty())
302 // URL to the OSD file this came from. May be empty.
303 void set_originating_url(const GURL
& url
) {
304 originating_url_
= url
;
306 const GURL
& originating_url() const { return originating_url_
; }
308 // The shortcut for this template url. May be empty.
309 void set_keyword(const std::wstring
& keyword
);
310 const std::wstring
& keyword() const;
312 // Whether to autogenerate a keyword from the url() in GetKeyword(). Most
313 // consumers should not need this.
314 // NOTE: Calling set_keyword() turns this back off. Manual and automatic
315 // keywords are mutually exclusive.
316 void set_autogenerate_keyword(bool autogenerate_keyword
) {
317 autogenerate_keyword_
= autogenerate_keyword
;
318 if (autogenerate_keyword_
)
321 bool autogenerate_keyword() const {
322 return autogenerate_keyword_
;
325 // Whether this keyword is shown in the default list of search providers. This
326 // is just a property and does not indicate whether this TemplateURL has
327 // a TemplateURLRef that supports replacement. Use ShowInDefaultList to
329 // The default value is false.
330 void set_show_in_default_list(bool show_in_default_list
) {
331 show_in_default_list_
= show_in_default_list
;
333 bool show_in_default_list() const { return show_in_default_list_
; }
335 // Returns true if show_in_default_list() is true and this TemplateURL has a
336 // TemplateURLRef that supports replacement.
337 bool ShowInDefaultList() const;
339 // Whether it's safe for auto-modification code (the autogenerator and the
340 // code that imports data from other browsers) to replace the TemplateURL.
341 // This should be set to false for any keyword the user edits, or any keyword
342 // that the user clearly manually edited in the past, like a bookmark keyword
343 // from another browser.
344 void set_safe_for_autoreplace(bool safe_for_autoreplace
) {
345 safe_for_autoreplace_
= safe_for_autoreplace
;
347 bool safe_for_autoreplace() const { return safe_for_autoreplace_
; }
349 // Images for this URL. May be empty.
350 void add_image_ref(const ImageRef
& ref
) { image_refs_
.push_back(ref
); }
351 const std::vector
<ImageRef
>& image_refs() const { return image_refs_
; }
353 // Convenience methods for getting/setting an ImageRef that points to a
354 // favicon. A TemplateURL need not have an ImageRef for a favicon. In such
355 // a situation GetFavIconURL returns an invalid url.
357 // If url is empty and there is an image ref for a favicon, it is removed.
358 void SetFavIconURL(const GURL
& url
);
359 GURL
GetFavIconURL() const;
361 // Set of languages supported. This may be empty.
362 void add_language(const std::wstring
& language
) {
363 languages_
.push_back(language
);
365 const std::vector
<std::wstring
>& languages() const { return languages_
; }
367 // Date this keyword was created.
369 // NOTE: this may be 0, which indicates the keyword was created before we
370 // started tracking creation time.
371 void set_date_created(Time time
) { date_created_
= time
; }
372 Time
date_created() const { return date_created_
; }
374 // Number of times this keyword has been explicitly used to load a URL. We
375 // don't increment this for uses as the "default search engine" since that's
376 // not really "explicit" usage and incrementing would result in pinning the
377 // user's default search engine(s) to the top of the list of searches on the
378 // New Tab page, de-emphasizing the omnibox as "where you go to search".
379 void set_usage_count(int count
) { usage_count_
= count
; }
380 int usage_count() const { return usage_count_
; }
382 // The list of supported encodings for the search terms. This may be empty,
383 // which indicates the terms should be encoded with UTF-8.
384 void set_input_encodings(const std::vector
<std::string
>& encodings
) {
385 input_encodings_
= encodings
;
387 void add_input_encoding(const std::string
& encoding
) {
388 input_encodings_
.push_back(encoding
);
390 const std::vector
<std::string
>& input_encodings() const {
391 return input_encodings_
;
394 // Returns the unique identifier of this TemplateURL. The unique ID is set
395 // by the TemplateURLModel when the TemplateURL is added to it.
396 IDType
id() const { return id_
; }
398 // If this TemplateURL comes from prepopulated data the prepopulate_id is > 0.
399 void set_prepopulate_id(int id
) { prepopulate_id_
= id
; }
400 int prepopulate_id() const { return prepopulate_id_
; }
403 friend class WebDatabaseTest
;
404 friend class WebDatabase
;
405 friend class TemplateURLModel
;
407 // Invalidates cached values on this object and its child TemplateURLRefs.
408 void InvalidateCachedValues() const;
410 // Unique identifier, used when archived to the database.
411 void set_id(IDType id
) { id_
= id
;}
413 std::wstring short_name_
;
414 std::wstring description_
;
415 TemplateURLRef suggestions_url_
;
417 GURL originating_url_
;
418 mutable std::wstring keyword_
;
419 bool autogenerate_keyword_
; // If this is set, |keyword_| holds the cached
420 // generated keyword if available.
421 bool show_in_default_list_
;
422 bool safe_for_autoreplace_
;
423 std::vector
<ImageRef
> image_refs_
;
424 std::vector
<std::wstring
> languages_
;
425 // List of supported input encodings.
426 std::vector
<std::string
> input_encodings_
;
432 // TODO(sky): Add date last parsed OSD file.
435 #endif // CHROME_BROWSER_TEMPLATE_URL_PARSER_H__