舊文件

此處文件僅供參考,請自行考量時效性與適用程度,其他庫藏文件請參考文件頁面
我們亟需您的協助,進行共筆系統搬移、及文件整理工作,詳情請查閱參與我們

「為 Firefox 建立 OpenSearch 搜尋模組」修訂間的差異

出自 MozTW Wiki

OpenSearch
(Revision as of 14:09 2007年六月16日)
 
(未顯示由 3 位使用者於中間所作的 3 次修訂)
行 1: 行 1:
 +
{{MDC|製作_OpenSearch_搜尋模組}}
 +
 
=OpenSearch=
 
=OpenSearch=
  
[[Firefox 2]]支援[http://opensearch.org/ OpenSearch]是Search plugins的格式. Plugins that use the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document OpenSearch description syntax] are compatible with IE 7 and Firefox. Because of this, they are the recommended format for use on the web.
+
[[Firefox 2]] 在搜尋插件(search plugins)上支援[http://opensearch.org/ OpenSearch]的格式. 這個使用[http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document OpenSearch 語法] 的插件同時相容 IE 7 Firefox. 正因如此, 網站製作時皆推薦該語法格式.
  
Firefox also supports additional search capabilities not included in the [http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document OpenSearch description syntax], such as search suggestions and the SearchForm element. This article will focus on creating OpenSearch-compatible search plugins that support these additional Firefox-specific features.
+
Firefox 除了[http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document OpenSearch 語法]也支援其他相容的搜尋格式, 像是 search suggestions the SearchForm element. 這篇文章將重點放在說明如何建立支援Firefox特徵的 OpenSearch 相容格式之搜尋插件.
  
 
OpenSearch description files can also be advertised as described in [[#Autodiscovery of search plugins|Autodiscovery of search plugins]], and can be installed programmatically as described in [[Adding search engines from web pages]].
 
OpenSearch description files can also be advertised as described in [[#Autodiscovery of search plugins|Autodiscovery of search plugins]], and can be installed programmatically as described in [[Adding search engines from web pages]].

於 2007年11月18日 (日) 23:03 的最新修訂

本文已經移往 Mozilla 開發者中心,請前往目前網址參考最新資訊。

OpenSearch

Firefox 2 在搜尋插件(search plugins)上支援OpenSearch的格式. 這個使用OpenSearch 語法 的插件同時相容 IE 7 及 Firefox. 正因如此, 網站製作時皆推薦該語法格式.

Firefox 除了OpenSearch 語法也支援其他相容的搜尋格式, 像是 search suggestions 和 the SearchForm element. 這篇文章將重點放在說明如何建立支援Firefox特徵的 OpenSearch 相容格式之搜尋插件.

OpenSearch description files can also be advertised as described in Autodiscovery of search plugins, and can be installed programmatically as described in Adding search engines from web pages.

OpenSearch description file

The XML file describing a search engine is actually quite simple, following the basic template below. Sections in italics need to be customized based on the needs of the specific search engine plugin you're writing.

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                       xmlns:moz="http://www.mozilla.org/2006/browser/search/">
<ShortName>engineName</ShortName>
<Description>engineDescription</Description>
<InputEncoding>inputEncoding</InputEncoding>
<Image width="16" height="16">data:image/x-icon;base64,imageData</Image>
<Url type="text/html" method="method" template="searchURL">
  <Param name="paramName1" value="paramName1"/>
  ...
  <Param name="paramNameN" value="paramValueN"/>
</Url>
<Url type="application/x-suggestions+json" template="suggestionURL"/>
<moz:SearchForm>searchFormURL</moz:SearchForm>
</OpenSearchDescription>
ShortName
A short name for the search engine.
Description
A brief description of the search engine.
InputEncoding
The encoding to use for the data input to the search engine.
Image
Base-64 encoded 16x16 icon representative of the search engine. One useful tool that you can use to construct the data to place here can be found here: The data: URI kitchen.
Url
Describes the URL or URLs to use for the search. The method attribute indicates whether to use a GET or POST request to fetch the result. The template attribute indicates the base URL for the search query.
Note: Internet Explorer 7 does not support POST requests.
There are two URL types you can specify:
  • type="text/html" is used to specify the URL for the actual search query itself.
  • type="application/x-suggestions+json" is used to specify the URL to use for fetching search suggestions.
For either type of URL, you can use {searchTerms} to substitute the search terms entered by the user in the search bar. Other supported dynamic search parameters are described in OpenSearch 1.1 parameters.
For search suggestion queries, the specified URL template is used to fetch a suggestion list in JavaScript Object Notation (JSON) format. For details on how to implement search suggestion support on a server, see Supporting search suggestions in search plugins.

檔案:SearchSuggestionSample.png

Param
The parameters that need to be passed in along with the search query, as key/value pairs. When specifying values, you can use {searchTerms} to insert the search terms entered by the user in the search bar.
Note: Internet Explorer 7 does not support this element.
SearchForm
The URL to go to to open up the search page at the site for which the plugin is designed to search. This provides a way for Firefox to let the user visit the web site directly.
Note: Since this element is Firefox-specific, and not part of the OpenSearch specification, we use of the "moz:" XML namespace prefix in the example above to ensure that other user agents that don't support this element can safely ignore it.

Autodiscovery of search plugins

A web site that offers a search plugin can advertise it so that Firefox users can easily download and install the plugin.

To support autodiscovery, you simply need to add one line to the <HEAD> section of your web page:

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

Replace the italicized items as explained below:

searchTitle
The name of the search to perform, such as "Search MDC" or "Yahoo! Search". This value should match your plugin file's ShortName.
pluginURL
The URL to the XML search plugin, from which the browser can download it.

If your site offers multiple search plugins, you can support autodiscovery for them all. For example:

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

This way, your site can offer plugins to search both by author and by title as separate entities.

除錯要訣

If there is a mistake in your Search Plugin XML, you could run into errors when adding a discovered plugin in Firefox 2. The error message may not be entirely helpful, however, so the following tips could help you find the problem.

如果您的搜尋模組 XML 檔案存在著錯誤,您可能在將該模組加入到 Firefox 2 時,遇到錯誤。而錯誤訊息可能不會很有用,然而,下面的要訣能幫你找到錯誤。

  • Be sure that your Search Plugin XML is well formed. You can check by loading the file directly into Firefox. Ampersands in the template URL need to be escaped with &amp; and tags need to be closed with a trailing slash or matching end tag.
  • 確定您的搜尋模組 XML 是完好的。您可以透過「直接載入到 Firefox」來檢查。另外,樣本 URL 中的「&」符號應該要以「&amp;」來脫逸。而且每一個標籤都要是封閉的─就是以反斜線結束、或是以結束標籤來結束─。
  • The xmlns attribute is important, without it you could get an error message indicating that "Bon Echo could not download the plugin from (URL)".
  • xmlns 屬性是非常重要的。缺少了它,您可能接到向這樣的錯誤訊息:「Bon Echo could not download the plugin from (URL)」
  • Note that you must include a text/html URL — search plugins including only Atom or RSS URL types (which pass, for example, the A9 OpenSearch validator) will also generate the "could not download the plugin" error.
  • 您所製作的模組必須包含一個 text/html URL — 搜尋模組若只包含 Atom 或 RSS 形式的 URL(就算能通過 A9 OpenSearch 驗證程式的驗證) 仍然會產生「could not download the plugin」這樣子的錯誤。

In addition, the search plugin service provides a logging mechanism that may be of use to plugin developers. Use about:config to set the pref 'browser.search.log' to true. Logging information will appear in Firefox's Error Console (Tools->Error Console) when search plugins are added.

此外,Firefox 的搜尋模組服務提供了一個可被模組開發者利用的歷程紀錄系統。使用 about:config 將 'browser.search.log' 設定改為 true。然後當模組被加入時,歷程紀錄就會出現在 Firefox 的錯誤主控台 (工具->錯誤主控台)。

延伸閱讀

個人工具