This document describes an experimental extension to the SearchBox API designed for search providers to allow them to integrate more tightly with Chrome’s Omnibox functionality. It is still early in development, and will change and evolve over time. This document will be kept up to date with the changes in trunk Chromium and is to be considered the authoritative reference on this new API. Overview When the Embedded Search API is enabled, Chrome will load a page from the user’s search provider in a background window and send it messages as appropriate when the user interacts with the Omnibox. It is up to the implementing page to respond to those messages as it sees fit. A typical interaction could go as follows:
--instant-url=”http://www.mysearchprovider.com/foo?bar=baz” Chrome will then load the page at that URL and attempt to interface with it via this API. Note that there are two known bugs with this method that we hope to have fixed soon: https://code.google.com/p/chromium/issues/detail?id=164873 https://code.google.com/p/chromium/issues/detail?id=164503 Reference // This interface is exposed as window.chrome.embeddedSearch to the embedded search page. interface EmbeddedSearch { // A function to call to navigate the current page. Can accept either an URL or // a restricted ID associated with a native suggestion. void navigateContentWindow(url); void navigateContentWindow(rid); // Interface to allow the embedded search page to interact with and control the // navigator searchbox. Exposed as window.chrome.embeddedSearch.searchBox. interface SearchBox { // This attribute returns the text the user has entered into the searchbox, not // including any automatic completion. readonly attribute DOMString value; // This attribute indicates that the user has done something to indicate they are // interested in their verbatim input and not in any completion, such as hitting // backspace. readonly attribute boolean verbatim; // The offset of the character that immediately follows the start of the selection in // the searchbox. readonly attribute unsigned long selectionStart; // The offset of the character that immediately follows the end of the selection in // the searchbox. readonly attribute unsigned long selectionEnd; // NOTE: Callback functions will eventually be migrated to an // addEventListener approach. // A callback function called by the browser whenever value, verbatim, // selectionStart, or selectionEnd change. There are no arguments. attribute Function onchange; // A callback function called by the browser when the user submits their input text, // typically by pressing enter. There are no arguments. attribute Function onsubmit; // The left and right margins of the text in the omnibox, used by the page to // position suggestions correctly below it. If the browser is rendering its UI in // right-to-left mode, then rtl will be set. readonly attribute unsigned long startMargin; readonly attribute unsigned long endMargin; attribute Function onmarginchange; readonly attribute unsigned boolean rtl; // The font face and font size used by the native input field. Suggestions should be // rendered in the same styling if possible to allow for correct alignment. readonly attribute DOMString font; readonly attribute unsigned long fontSize; // An array containing suggested completions from the browser for the user's typed // prefix. Should be populated as swiftly as possible after user input. // See format note for NativeSuggestion below---most importantly, each // nativeSuggestion has a corresponding restricted ID which is to be used to // reference it in future API calls. readonly attribute Array<NativeSuggestion> nativeSuggestions; // Fired when the value of nativeSuggestions has changed. attribute Function onnativesuggestions; // Takes in a list of ClientSuggestion objects (see below) that the client of this // API wishes to have deduped against the current set of native suggestions. It sets // the duplicateOf bit appropriately to be equal to the restricted ID of the native // suggestion it is a duplicate of. Note that if the list contains more than 6 items // or if the function has already been called once for the current set of // nativeSuggestions then it will do nothing and return false. Otherwise returns // true. bool markDuplicateSuggestions(clientSuggestions); // This is a callback function called by the browser to allow the embedded search // page to handle certain keypress events, such as arrow down and arrow up. A normal // MouseEvent with the keycode of the pressed key is passed in as an argument. attribute Function onkeypress; // Forces the text value in the omnibox to a given text string. Does not trigger // onchange nor fetch new native suggestions. // type - for what icon to display. An enum: // 0 = query // 1 = url void setValue(text, type); // Version of the above but for a native suggestion---Chrome will dereference the // provided restricted id into the proper URL string to display. void setRestrictedValue(rid, type); // Sets the suggested autocomplete text in the omnibox. // opt_completion_style used to specify the desired behavior of the user hitting the // enter key or otherwise submitting the contents of the omnibox when this suggestion // is being displayed. Default is no preference. // valid values: // 0 = no preference // 1 = accept suggestion on submit // 2 = discard suggestion and accept verbatim input on submit // This is currently used in Chrome to determine the visual style of the completion - // if a completion is to be accepted on enter, it is displayed as selected blue text, // and if it is to be discarded on enter it is displayed as light grey completion // text. void setAutocompleteText(text, opt_completion_style); // Version of the above but for a native suggestion---Chrome will dereference the // provided restricted id into the proper string to display. void setRestrictedAutocompleteText(rid, opt_style); // A function called by the embedded search page to indicate that it has content it // wishes to display to the user. During regular navigation, the embedded search page // is hidden from the user and it must call this function to indicate to Chrome that // it wishes to be displayed. // NOTE: due to the inherently asynchronous nature of the interface, the browser // isn't guaranteed to honor this call. The user may have taken an action---such // as switching tabs---that renders this call invalid. // If opt_height is omitted, it is assumed to be 100%. If explicitly set to 0, the // overlay is hidden. void showOverlay(opt_height); // Whether or not the native omnibox would prefer the page show Instant results. // If true or undefined, the page may show instant results or may display only // suggestions as it chooses, but if this is false then the user has expressed an // explicit preference to not see Instant results, so Instant results must not be // shown. readonly attribute boolean displayInstantResults; // Requests the searchbox to enter (or exit) a mode where it is not visibly focused // but if the user presses a key will capture it and focus itself. Conceptually // similar to an invisible focus() call. void startCapturingKeyStrokes(); void stopCapturingKeyStrokes(); // Attribute and listener to detect if the searchbox is currently capturing user key // strokes. readonly attribute boolean isKeyCaptureEnabled; attribute Function onkeycapturechange; }; // interface Searchbox // Interface to allow the embedded search page to interact with and control the // New Tab Page. Exposed as window.chrome.embeddedSearch.newTabPage. interface NewTabPage { // A callback function called when the embedded search page should display some // aspect of the user's custom UI theme. // Fired when (1) the theme area height changes (e.g. on a browser resize), or // (2) the theme changes. attribute Function onthemeareaheightchange; // Fired when the theme changes. // Note that this is somewhat redundant with the above and may be removed. attribute Function onthemeareachange; // The height of the theme area. // Only set when the overlay is showing the NTP and the theme background is not // top-aligned (i.e. themeBackgroundInfo.imageUrl is nonempty and // themeBackgroundInfo.imageVerticalAlignment is not 'top'). readonly long themeAreaHeight; // Only set when the overlay is showing the NTP. readonly attribute ThemeBackgroundInfo themeBackgroundInfo; }; // interface NewTabPage }; // Format for a native suggestion object supplied by the browser. NativeSuggestion { // Chrome-side provider for this suggestion, such as "HistoryQuickProvider". // See The Chromium code at chrome/browser/autocomplete/* for available providers. readonly attribute DOMString provider; // DIVs with the correctly bolded display text of the suggestion’s url and title in its // Shadow DOM. (The shadow DOM inherits most css styling from its parent.) These are // provided by Chrome for use on the page. Clients of this API must not attempt to // break the Shadow DOM isolation and read the contents of these elements. // An example of one of these elements would be, if the user has typed foo: // <div><shadow><b>foo</b>barbaz.com</shadow></div> // The font face is set to be the font used by the Omnibox on the user’s platform to // allow for easy alignment. These elements have a fixed width and use // text-overflow:ellipsis. attribute Element titleNode; attribute Element urlNode; // This element is similar to the above Elements, but with both title and URL in one // merged element. It matches the following style: // <div><shadow><span class=chrome_url>url</span><span class=chrome_separator> - // </span><span class=chrome_title>title</span></shadow></div> // Using this element is the recommended way of rendering this suggestion. attribute Element combinedNode; // An ID for this suggestion---will be used to identify this suggestion to // the browser if the user indicates they want to select it or navigate to it. Can be // passed in to the functions setRestrictedValue, setRestrictedAutocompleteText, and // acceptSuggestion. readonly attribute unsigned long rid; // Metadata about this suggestion deemed safe to expose to the search provider, to be // used to rank this suggestion with those returned by the search provider. readonly attribute Object rankingData { // The relevance score currently returned by native search providers, on a 0-1500 // scale. If this value is over 1300, then the browser has determined it is of // sufficiently high relevance to trump any suggestion from the search provider, and // the embedded search page must render it as the top suggestion. By the time // onnativesuggestions has been called the browser will have already autocompleted // the value of this suggestion inline in the omnibox itself for performance reasons, // with the completion style of accepting the suggestion on commit. The UI of the // embedded search page should reflect this, if possible. readonly attribute unsigned long relevance; }; }; // Format of an URL suggestion from the embedded search page passed into the // markDuplicateSuggestions function. ClientSuggestion { // URL of this suggestion. readonly attribute String url; // If the binary determines that this suggestion is a duplicate of one of the native // suggestions it has supplied for this prefix, it will fill in this attribute with the // restricted id of its duplicate. attribute Number duplicateOf; } // Format of the ThemeBackgroundInfo object which indicates information about the user's // chosen custom UI theme necessary for correct rendering of the new tab page. ThemeBackgroundInfo { // Theme background-color. Always present. attribute String colorRgba; // NOTE: The following fields are all optional. // Theme background-image url, if any. readonly attribute String imageUrl; // Theme background-position x component. readonly attribute String imageHorizontalAlignment; // Theme background-position y component. readonly attribute String imageVerticalAlignment; // Theme background-repeat. readonly attribute String imageTiling; // Theme attribution url, if any. readonly attribute String attributionUrl; }; Last edited: Friday, February 15, 2012, 11:00am PST |
Embedded Search API (Draft) |