SearchBox API

OBSOLETE - replaced by the Embedded Search API.In addition to OpenSearch compliance, Chromium also provides an experimental JavaScript API that enables the default search provider to interact with the Omnibox. This allows the search page to instantly respond to user interaction without reloading the page. It also allows the search page to communicate autocompletion suggestions. This page provides the technical specification for the SearchBox API. Status of this document: Editor's Draft March 19, 2011.This is a work in progress and may change without any notices. This API has been proposed to the WHATWG and we are eager to formally standardize it as it stabilizes. Please send comments to tonyg at chromium dot org.

1. WebIDL interfaces

Note that this entire interface is only available to the page the user has selected as the default search provider. The searchBox object is not exposed to general pages. See section 1.2.1 for details.

1.1 SearchBox interface

interface SearchBox { readonly attribute DOMString value; readonly attribute boolean verbatim; readonly attribute unsigned long selectionStart; readonly attribute unsigned long selectionEnd; readonly attribute unsigned long x; readonly attribute unsigned long y; readonly attribute unsigned long width; readonly attribute unsigned long height; void setSuggestions(in Object suggestions);          attribute Function onchange;          attribute Function onsubmit;          attribute Function oncancel;          attribute Function onresize;};

1.1.1 Attributes

These attributes describe the state of the user agent's search box to the search page. All attributes must be "live" and valid throughout the lifetime of the page.

value of type DOMString

This attribute must return the text that has been entered into the search box.

verbatim of type boolean

This attribute must return true if and only if the user agent suggests that the search page treat value as a verbatim search query (as opposed to a partially typed search query). Otherwise this attribute must return false. It is recommended that the user agent return true in the following circumstances:

• The user presses the forward delete key at the end of an input.
• The user highlights an option in the search box's dropdown and value is updated to reflect the option.
• The user agent in any way overridden the value entered by the user.

selectionStart of type unsigned long

This attribute must return the offset (in logical order) to the character that immediately follows the start of the selection in the search box. If there is no selection, then it must return the offset (in logical order) to the character that immediately follows the text entry cursor. Note that in the case there is no explicit text entry cursor, the cursor is implicitly at the end of the input.

selectionEnd of type unsigned long

This attribute must return the offset (in logical order) to the character that immediately follows the end of the selection in the search box. If there is no selection, then it must return the offset (in logical order) to the character that immediately follows the text entry cursor. Note that in the case there is no explicit text entry cursor, the cursor is implicitly at the end of the input.

x of type unsigned long

This attribute must return the horizontal offset (in pixels relative to the window's origin) of the portion of the search box that overlaps with the window (i.e. the search box's drop down menu). If the search box does not overlap the window, this attribute must return zero.

y of type unsigned long

This attribute must return the vertical offset (in pixels relative to the window's origin) of the portion of the search box that overlaps with the window (i.e. the search box's drop down menu). If the search box does not overlap the window, this attribute must return zero.

width of type unsigned long

This attribute must return the horizontal width in pixels of the portion of the search box that overlaps with the window (i.e. the search box's drop down menu). If the search box does not overlap the window, this attribute must return zero.

height of type unsigned long

This attribute must return the vertical height in pixels of the portion of the search box that overlaps with the window (i.e. the search box's drop down menu). If the search box does not overlap the window, this attribute must return zero.

1.2.2 Methods

This method allows the search page to control the state of the user agent's search box.

setSuggestions

This method accepts one argument, an object in JavaScript Object Notation form. It must adhere to the following JSON specification.

{ suggestions: [ { value: "..." }, { value: "..." } ] }

suggestions of type array - An ordered array of suggestions to be displayed. Note that calling this method with an empty suggestions array effectively clears search-page-provided-suggestions.

value of type string - The string completion for this suggestion.

The user agent must process suggestions as follows:

1. Let search-page-provided-suggestions be an initially empty array of strings.
2. Upon invoking setSuggestions, atomically replace all items in search-page-provided-suggestions with the value of each object in the suggestions array.

If the first search-page-provided-suggestions starts with the current search box value, it is recommended that the user agent display it as an inline autocomplete option. It is recommended that the user agent display the remaining N search-page-provided-suggestions as autocomplete options in a drop down menu below the search box input.

1.2.3 Event handlers

These event handlers allow the search page to register to receive notifications of changes in the search box attributes.

onchange

If the value of this attribute is a Function, that function must be called when the value of any of the value, verbatim, selectionStart or selectionEnd attributes is changed.

onsubmit

If the value of this attribute is a Function, that function must be called when the user commits the search query. It is recommended that the user agent consider the search query committed when the user presses enter/return.

oncancel

If the value of this attribute is a Function, that function must be called when the user cancels the search query. It is recommended that the user agent consider the search query cancelled when the search box loses focus.

onresize

If the value of this attribute is a Function, that function must be called when the value of any of the x, y, width, or height attributes is changed.

1.2 Navigator interface

NOTE: Because the SearchBox interface is still under development, the Chromium implementation exposes it under window.chrome instead of window.navigator. Some form of vendor prefixing is typical before new interfaces are standardized.

[Supplemental]interface Navigator { readonly attribute SearchBox searchBox;};

1.2.1 Attributes searchBox

Upon creation of a new browsing context, if the location indicates that the page is the user's default search provider, a new SearchBox instance must be created. If there is a SearchBox instance for the current browser context (the page is the default search provider), this attribute must return the current SearchBox instance. Otherwise this attribute must not be exposed to the DOM.

2. Example usage

This trivial example demonstrates how a default search provider may obtain a reference to the SearchBox instance, register for events, read state and set state.

var searchBox = window.navigator.searchBox;searchBox.onchange = function() {  if (this.selectionStart == this.selectionEnd &&      this.selectionStart == this.value.length)    alert('Cursor is at end of input');  alert('Setting suggestions for: ' + this.value);  this.setSuggestions({    suggestions: [      { value: "one"      },      { value: "two"      }    ]  });}searchBox.onsubmit = function() {  alert('User searched for: ' + this.value);}searchBox.oncancel = function() {  alert('Query when user cancelled: ' + this.value);}searchBox.onresize = function() {  alert('Resized to: ' +        [this.x,         this.y,         this.width,         this.height].join(','));}

3. Change log