Adding search engines from web pages

Firefox allows JavaScript code to install search engine plugins, and supports two search engine plugin formats: OpenSearch, and Sherlock.

Note: Starting with Firefox 2, OpenSearch is the preferred search format for Firefox. Sherlock support will be removed in the future (bug 862137).

When JavaScript code attempts to install a search plugin, Firefox presents an alert asking the user for permission to install the plugin.

Installing OpenSearch plugins

To install an OpenSearch plugin, you need to use the window.external.AddSearchProvider() DOM method. The syntax for this method is:

window.external.AddSearchProvider(engineURL);

Where engineURL is the absolute URL to the XML file for the search engine plugin.

Note: OpenSearch support is available only in Firefox 2 and later.

Installing Sherlock plugins

Deprecated
This feature has been removed from the Web. Though some browsers may still support it, it is in the process of being dropped. Do not use it in old or new projects. Pages or Web apps using it may break at any time.

To install a Sherlock plugin, you need to call window.sidebar.addSearchEngine(), the syntax for which is:

window.sidebar.addSearchEngine(engineURL, iconURL, suggestedName, suggestedCategory);
  • The engineURL parameter is the URL to the Sherlock plugin (a ".src" file) to install.
  • iconURL is the URL to an icon to associate with the plugin.
  • The suggestedName parameter is only used when prompting the user for permission to install the plugin, so that a message such as "Do you want to install suggestedName from engineURL?" can be displayed.
  • The suggestedCategory parameter is not used. You should specify either an empty string ("") or null.

For details on Sherlock, visit http://developer.apple.com/macosx/sherlock/

Browser search engine capability detection

Since the search engine addition APIs have changed between Firefox 1.5 and Firefox 2, and since Firefox 1.5 does not support OpenSearch description files, web page authors that want to add search engines in a backwards compatible way (i.e., that will work in Firefox 1.5, Firefox 2.0, or IE 7) must support both Sherlock and OpenSearch formats, and must detect the browser's capabilities accordingly. The following code snippet is an example of how this can be done:

 

function installSearchEngine() {
 if (window.external && ("AddSearchProvider" in window.external)) {
   // Firefox 2 and IE 7, OpenSearch
   window.external.AddSearchProvider("http://example.com/search-plugin.xml");
 } else if (window.sidebar && ("addSearchEngine" in window.sidebar)) {
   // Firefox <= 1.5, Sherlock
   window.sidebar.addSearchEngine("http://example.com/search-plugin.src",
                                  "http://example.com/search-icon.png",
                                  "Search Plugin", "");
 } else {
   // No search engine support (IE 6, Opera, etc).
   alert("No search engine support");
 }
}

Document Tags and Contributors

Last updated by: Yoshino,