为 Firefox 创建 OpenSearch 插件

Firefox 2 支持使用 OpenSearch 格式开发搜索引擎插件. 使用 OpenSearch 格式开发能够在IE 7 以及 Firefox上实现兼容. 这是这种语法被推荐使用的原因.

Firefox 也支持不被包括在 OpenSearch格式中的其它的搜索功能,例如搜索建议（search suggestion）以及 SearchForm 元素. 这篇文章主要关注创建与OpenSearch格式兼容的支持额外的firefox特殊特征的搜索插件.

OpenSearch 描述文件也能被如在 Autodiscovery of search plugins 中描述的一样被advertised(道歉这里不知如何翻译) ,并且能够如在 Adding search engines from web pages中所说的进行编程安装.

OpenSearch 描述文件

遵循以下的模板，你就会发现通过 XML 文件写一个搜索引擎实际上是如此的简单。粗体字部分需要根据具体你所写的搜索引擎需要来进行定制。

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="https://a9.com/-/spec/opensearch/1.1/"
                       xmlns:moz="https://www.mozilla.org/2006/browser/search/">
  <ShortName>engineName</ShortName>
  <Description>engineDescription</Description>
  <InputEncoding>inputEncoding</InputEncoding>
  <Image width="16" height="16" type="image/x-icon">data:image/x-icon;base64,imageData</Image>
  <Url type="text/html" method="method" template="searchURL">
    <Param name="paramName1" value="paramValue1"/>
    ...
    <Param name="paramNameN" value="paramValueN"/>
  </Url>
  <Url type="application/x-suggestions+json" template="suggestionURL"/>
  <moz:SearchForm>searchFormURL</moz:SearchForm>
</OpenSearchDescription>

ShortName: 对搜索引擎的简称; 限制: 名称仅能包含16个字符以下的纯文本. 名称不能包含HTML标志或其他标志.

Description: 对于搜索引擎的简单描述; 限制: 描述仅能包含少于1024个字符的纯文本. 名称不能包含HTML标志或其他标志.

InputEncoding: 向搜索引擎所输内容的字符编码.例如: <InputEncoding>UTF-8</InputEncoding>.

Image

使用指向一个图标的URL来代表这个搜索引擎. 可能的话, 应提供16x16大小的"image/x-icon"类型的图像以及一个64x64大小的 "image/jpeg" 或 "image/png"类型的图像. 链接也可以使用 data: URI scheme. The data: URI kitchen在这能找到一个能有效地帮助你构建写在此处的数据的工具.

<Image height="16" width="16" type="image/x-icon">https://example.com/favicon.ico</Image>
  OR
<Image height="16" width="16">data:image/x-icon;base64,AAABAAEAEBAAA ... DAAA=</Image>

Firefox以base64编码的data: URI (搜索插件被保存在 profile中的 "searchplugins" 文件夹) 缓存此图标. 当这完成时， http: URIs 被改变为 data: URIs.

Url: 描述用来实现搜索请求的一个或多个URL. method 属性决定使用 GET 还是 POST请求来获取返回的数据. template 属性指定实现搜索请求的 URL.; 注意: IE7 不支持 POST 请求.

这是两种firefox支持的URL类型:

type="text/html" 用来指定进行搜索查询的URL.
type="application/x-suggestions+json" 用来指定获取搜索建议（search suggestions）的URL.

这两种URL任何一种你都能使用 {searchTerms}来替换用户在搜索栏中输入的搜索内容. 其他支持的动态搜索参数可见 OpenSearch 1.1 parameters.

对使用搜索建议查询来说, URL template用来获取JSON格式的建议列表. 若需要知道关于如何在服务器上实现搜索建议支持, 请见 Supporting search suggestions in search plugins.

Image:SearchSuggestionSample.png

Param: 这个参数用来包括那些需要和搜索查询一起被传递的作为键值对的参数. 你能使用{searchTerms}来指代用户输入的搜索条目.; 注意: IE7不支持此元素.

SearchForm: 跳往搜索页的 URL. 这使得Firefox能让用户直接浏览目的网站.; 注意: 这个元素是firefox限定的, 并不是 OpenSearch 的一部分, 我们在例子中使用 "moz:" XML命名前缀来确保其它的不支持此元素的用户代理能安全地忽略此元素.

自动搜寻搜索插件

提供搜索插件的网站能宣传自己以使firefox使用者能容易地下载并安装此插件.

要支持自动搜寻你仅需在你网页的<head> 中加上一条:

<link rel="search" type="application/opensearchdescription+xml" title="searchTitle" href="pluginURL">

斜体字部分解释如下:

searchTitle: 搜索的名称, 如 "Search MDC" or "Yahoo! Search". 这个值应该与你在插件文件中的ShortName相一致.

pluginURL: 指向 XML搜索插件的URL, 能让浏览者下载插件.

如果你的网站提供多个插件, 你能为他们每一个都支持自动搜寻功能. 例如:

<link rel="search" type="application/opensearchdescription+xml" title="MySite: By Author" href="https://www.mysite.com/mysiteauthor.xml">
<link rel="search" type="application/opensearchdescription+xml" title="MySite: By Title" href="https://www.mysite.com/mysitetitle.xml">

这样，你的网站提供的插件就能同时以作者和名称分别作为搜索条目而被搜索.

为 OpenSearch 插件支持自动更新

Firefox 3.5 note

This section covers a feature introduced in Firefox 3.5.

从Firefox 3.5开始, OpenSearch 插件能够自动更新. 要支持这个, 需要包括一个额外的 "application/opensearchdescription+xml"类型Url 元素. rel属性需要设为 "self" ， template 属性需要是指向能自动更新的OpenSearch文档的 URL.

例如:

<Url type="application/opensearchdescription+xml"
     rel="self"
     template="https://www.foo.com/mysearchdescription.xml" />

注意: addons.mozilla.org (AMO) 不支持 OpenSearch 插件的自动更新. 如果你想将你的插件发布在 AMO上, 你不应该使用自动更新.

排错指南

如果你的搜索插件有错误, 当在firefox2中添加插件时会出错. 然而，错误信息可能并不是完全有所帮助的, 因此接下来的建议能帮你发现问题.

你的服务器应当运行使用MIME类型为application/opensearchdescription+xml的 OpenSearch 插件.
确保你的搜索插件正确地格式化了. 你能通过直接将插件加载入firefox来检查. template URL 中的&符号需要使用 &amp代替;标签需要以斜杠或是相匹配的结束标志结束。
xmlns属性是很重要的, 没有了他你会得到 "Firefox could not download the search plugin from: (URL)"错误信息.
注意你必须包含一个 text/html URL — 仅包含 Atom 或 RSS URL 类型 (有效但firefox不支持)的插件将产生 "could not download the search plugin"错误.
远程获取的收藏夹图标大小不能超过10KB (见 bug 361923).

另外, 搜索插件服务提供了日志机制，这对于插件开发者来说可能能起到一定作用 . 使用 about:config 设定 'browser.search.log' 为 true. 插件被加载后日志信息将显示在火狐的 Error Console 中(Tools->Error Console).

参考资料

OpenSearch Documentation, OpenSearch Documentation about the Url and Param element
Technorati.com has a working osd.xml
More on Autodiscovery difficulties at bugzilla bug 340208
data: URI scheme
searchplugins.net - create OpenSearch plugins for use with Firefox 2. List of generated search plugins
Ready2Search - create OpenSearch plugins. Customized Search through Ready2Search