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.

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.

Installing Sherlock plugins

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");
 }
}