Contents

  1. Manifest

  2. The sample

  3. API reference: chrome.omnibox

    1. Methods

      1. setDefaultSuggestion

    2. Events

      1. onInputCancelled
      2. onInputChanged
      3. onInputEntered
      4. onInputStarted

    3. Types

      1. SuggestResult

The OmniBox application interface allows you to register a keyword with the Google Chrome address bar, also known as the Omnibox.

When a user enters your extension keywords, the user starts interacting with your extension. Each keystroke is sent to your extension, which provides suggestions in response.

Suggestions can be formatted in a variety of ways. When the user accepts the suggestion, your extension is notified that it can perform the action.

Manifest

To use the OmniBox application interface, you must include the Omnibox key fields in the Manifest. You need to specify a 16×16 icon so that when the user enters a keyword, it will be displayed in the address bar.

Such as:

{" name ":" Aaron 's omnibox extension ", "version" : "1.0" * * "omnibox" : {" keyword ":" Aaron "}, * * * * "ICONS" : {* * * * "16" : "16-full-color.png"** **},** "background_page": "background.html" }Copy the code

Tip: Chrome automatically creates 16×16 pixel ICONS in grayscale mode. You should provide a full-color version of the icon so it can be used in other scenarios. For example, Context Menus API

Use a full-color 16×16 pixel icon.

The sample

An example of using this API can be found on the Sample Page. .

Application interface reference: Chrome.omniBox

Methods

method name

void chrome.module.methodName(, “)

Undocumented.

A description from the json schema def of the function goes here.

Parameters

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {... };Copy the code

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

setDefaultSuggestion

void chrome.omnibox.setDefaultSuggestion(, object suggestion)

Undocumented.

Sets the default recommended description and style. The default recommendation is the first suggested display text displayed under the URL address bar

Parameters

suggestion ( optional enumerated Type array of object )

Undocumented.

SuggestResult is a partial object with no ‘content’ argument. See SuggestResult for a description of this parameter.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

description ( optional enumerated Type array of string )

Undocumented.

The text displayed in the default suggestion can contain ‘%s’ and can be replaced by user input.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

Returns

Callback function

The callback parameter should specify a function that looks like this:

If you specify the callback parameter, it should specify a function that looks like this:

function(Type param1, Type param2) {... };Copy the code

This function was added in version . If you require this function, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

Events

onInputCancelled

chrome.omnibox.onInputCancelled.addListener(function() {… });

Undocumented.

The user ended the keyboard input session, but did not accept the input (the input was cancelled).

Parameters

onInputChanged

chrome.omnibox.onInputChanged.addListener(function(string text, function suggest) {… });

Undocumented.

The user modifies the input in the Omnibox.

Parameters

text ( optional enumerated Type array of string )

Undocumented.

Description of this parameter from the json schema.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

suggest ( optional enumerated Type array of function )

Undocumented.

A callback to the onInputChanged event that sends a suggestion back to the browser when the event occurs.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

Parameters

paramName ( optional enumerated Type array of SuggestResult array of paramType paramType )

Undocumented.

Suggested results, array.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

onInputEntered

chrome.omnibox.onInputEntered.addListener(function(string text) {… });

Undocumented.

The user receives the data in the Omnibox.

Parameters

text ( optional enumerated Type array of string )

Undocumented.

Description of this parameter from the json schema.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

onInputStarted

chrome.omnibox.onInputStarted.addListener(function() {… });

Undocumented.

The user enters the extended keywords and begins a keyboard input session. This event is sent at the beginning of a session, before other events, and only once per session.

Parameters

Types

SuggestResult

paramName ( optional enumerated Type array of object )

Undocumented.

Suggest results.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

content ( optional enumerated Type array of string )

Undocumented.

Text in the URL area that is sent to the extension when the user selects the item.

This parameter was added in version . You must omit this parameter in earlier versions, and you may omit it in any version. If you require this parameter, the manifest key minimum_chrome_version can ensure that your extension won’t be run in an earlier browser version.

description ( optional enumerated Type array of string )

Undocumented.

The text displayed in The URL drop-down list. You can include an XML style tag. The supported tags are ‘URL’ (as a syntactic URL), ‘match’ (as highlighted text to match user request data), and ‘DIM’ (as grey auxiliary text). Styles can be nested.

Options page

To allow users to set your extension functionality, you may need to provide an options page. If you provide the options page, a link will be provided on the extension management page chrome:// Extensions. Click the options link to open your options page.

Define your options page in manifest

{
  "name": "My extension",
  ...
  **"options_page": "options.html"**,
  ...
}
Copy the code

Write your options page

Here is an example of an options page:

<html> <head><title>My Test Extension Options</title></head> <script type="text/javascript"> // Saves options to localStorage. function save_options() { var select = document.getElementById("color"); var color = select.children[select.selectedIndex].value; localStorage["favorite_color"] = color; // Update status to let user know options were saved. var status = document.getElementById("status"); status.innerHTML = "Options Saved."; setTimeout(function() { status.innerHTML = ""; }, 750); } // Restores select box state to saved value from localStorage. function restore_options() { var favorite = localStorage["favorite_color"]; if (! favorite) { return; } var select = document.getElementById("color"); for (var i = 0; i < select.children.length; i++) { var child = select.children[i]; if (child.value == favorite) { child.selected = "true"; break; } } } </script> <body onload="restore_options()"> Favorite Color: <select id="color"> <option value="red">red</option> <option value="green">green</option> <option value="blue">blue</option> <option value="yellow">yellow</option> </select> <br> <button onclick="save_options()">Save</button> </body> </html>Copy the code

Matters needing attention

  • This feature takes effect on chromium 4.0.222.x or later.
  • To encourage consistency between the options pages of different extensions, we plan to provide some default CSS styles. You can follow updates at crbug.com/25317.