mozilla

Revision 135372 of Creacion de plugins OpenSearch para Firefox

  • Enlace amigable (slug) de la revisión: Creacion_de_plugins_OpenSearch_para_Firefox
  • Título de la revisión: Creacion de plugins OpenSearch para Firefox
  • Id de la revisión: 135372
  • Creada:
  • Creador: Fenomeno
  • ¿Es la revisión actual? No
  • Comentario /* El fichero de descripción OpenSearch */

Contenido de la revisión

{{wiki.template('Traducción', [ "inglés", "Creating OpenSearch plugins for Firefox", "en" ])}}


OpenSearch

Firefox 2 admite el formato de descripción OpenSearch para complementos (plugins) de búsqueda. Aquellos complementos que usen la sintaxis OpenSearch son compatibles con Firefox e Internet Explorer 7. Por ello es el formato recomendado para cualquier nuevo desarrollo.

Firefox admite además capacidades de búsqueda adicionales no incluidas en la sintaxis de descripción OpenSearch, tales como las "sugerencias de búsqueda" y el elemento SearchForm. Este artículo se centrará en la creación de complementos compatibles con OpenSearch que empleen estas capacidades adicionales de Firefox.

Además, los ficheros de descripción OpenSearch pueden ser anunciados dentro de una página HTML de forma que puedan ser descubiertos automáticamente por el navegador (esto se describe en Detección automática de motores de búsqueda.

Por último, estos complementos, pueden ser instalados mediante código tal y como se describe en Añadir motores de búsqueda desde páginas web.

El fichero de descripción OpenSearch

El fichero XML que describe un motor de búsqueda es bastante sencillo, tal y como se puede ver en la plantilla básica que se muestra más abajo. Las secciones en negrita deben ser personalizadas basándonos en las necesidades particulares del motor para el que estamos escribiendo nuestro complemento.

<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="paramValue1"/>
  ...
  <Param name="paramNameN" value="paramValueN"/>
</Url>
<Url type="application/x-suggestions+json" template="suggestionURL"/>
<moz:SearchForm>searchFormURL</moz:SearchForm>
</OpenSearchDescription>
ShortName
Nombre corto para el motor de búsqueda.
Description
Descripción del motor de búsqueda.
InputEncoding
Codificación de caracteres a emplear en los datos que se envían al motor de búsqueda. Por ejemplo, "UTF-8".
Image
Icono de 16x16 codificado en Base-64 que represente al motor de búsqueda. Puedes encontrar una utilidad para generar estos datos en: The data: URI kitchen.
Url
Describe la(s) URL(s) a emplear para la búsqueda. El atributo method indica si se debe emplear una petición GET o POST para obtener los resultados.
Nota: Internet Explorer 7 no admite peticiones POST.
Firefox admite dos tipos de URL en el campo type:
  • type="text/html" se usa al especificar la URL a donde se va a enviar la petición de búsqueda.
  • type="application/x-suggestions+json" se usa al especificar la URL de donde se van a obtener las sugerencias de búsqueda.
El atributo template indica la forma en que se construirá la URL para la consulta. Dentro de este atributo se pueden introducir plantillas que se expanden de forma dinámica; la más habitual es {searchTerms}, la cual se expande a los términos de búsqueda introducidos por el usuario en la barra de búsquedas. En OpenSearch 1.1 parameters se describen los otros tipos admitidos.
Para consultas que devuelven sugerencias de búsqueda, la URL descrita en template se usa para obtener una lista de sugerencias en el formato JSON (JavaScript Object Notation). Para saber más sobre como incorporar sugerencias de búsqueda en el lado del servidor, ver Supporting search suggestions in search plugins.

Image: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 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.

Troubleshooting Tips

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.

  • 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.
  • The xmlns attribute is important, without it you could get an error message indicating that "Firefox could not download the search plugin from: (URL)".
  • Note that you must include a text/html URL — search plugins including only Atom or RSS URL types (which is valid, but Firefox doesn't support) will also generate the "could not download the search plugin" error.
  • Remotely fetched favicons must not be larger than 10KB (see {{template.Bug(361923)}}).

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.

Reference Material

Interwiki link

{{ wiki.languages( { "ca": "ca/Creaci\u00f3_de_connectors_OpenSearch_per_al_Firefox", "en": "en/Creating_OpenSearch_plugins_for_Firefox", "fr": "fr/Cr\u00e9ation_de_plugins_OpenSearch_pour_Firefox", "ja": "ja/Creating_OpenSearch_plugins_for_Firefox" } ) }}

Fuente de la revisión

<p>
{{wiki.template('Traducción', [ "inglés", "Creating OpenSearch plugins for Firefox", "en" ])}}
</p><p><br>
</p>
<h2 name="OpenSearch">OpenSearch</h2>
<p><a href="es/Firefox_2">Firefox 2</a> admite el formato de descripción <a class="external" href="http://opensearch.org/">OpenSearch</a> para complementos (<i>plugins</i>) de búsqueda. Aquellos complementos que usen <a class="external" href="http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document">la sintaxis OpenSearch</a> son compatibles con Firefox e Internet Explorer 7. Por ello es el formato recomendado para cualquier nuevo desarrollo.
</p><p>Firefox admite además capacidades de búsqueda adicionales no incluidas en <a class="external" href="http://www.opensearch.org/Specifications/OpenSearch/1.1#OpenSearch_description_document">la sintaxis de descripción OpenSearch</a>, tales como las "sugerencias de búsqueda" y el elemento <code>SearchForm</code>. Este artículo se centrará en la creación de complementos compatibles con OpenSearch que empleen estas capacidades adicionales de Firefox.
</p><p>Además, los ficheros de descripción OpenSearch pueden ser anunciados dentro de una página HTML de forma que puedan ser descubiertos automáticamente por el navegador (esto se describe en <a href="#Autodiscovery_of_search_plugins">Detección automática de motores de búsqueda</a>.
</p><p>Por último, estos complementos, pueden ser instalados mediante código tal y como se describe en <a href="es/A%c3%b1adir_motores_de_b%c3%basqueda_desde_p%c3%a1ginas_web">Añadir motores de búsqueda desde páginas web</a>.
</p>
<h2 name="El_fichero_de_descripci.C3.B3n_OpenSearch">El fichero de descripción OpenSearch</h2>
<p>El fichero XML que describe un motor de búsqueda es bastante sencillo, tal y como se puede ver  en la plantilla básica que se muestra más abajo. Las secciones en negrita deben ser personalizadas basándonos en las necesidades particulares del motor para el que estamos escribiendo nuestro complemento.
</p>
<pre class="eval">&lt;OpenSearchDescription xmlns="<span class="plain">http://a9.com/-/spec/opensearch/1.1/</span>"
                       xmlns:moz="<span class="plain">http://www.mozilla.org/2006/browser/search/</span>"&gt;
&lt;ShortName&gt;<b>engineName</b>&lt;/ShortName&gt;
&lt;Description&gt;<b>engineDescription</b>&lt;/Description&gt;
&lt;InputEncoding&gt;<b>inputEncoding</b>&lt;/InputEncoding&gt;
&lt;Image width="16" height="16"&gt;data:image/x-icon;base64,<b>imageData</b>&lt;/Image&gt;
&lt;Url type="text/html" method="<b>method</b>" template="<b>searchURL</b>"&gt;
  &lt;Param name="<b>paramName1</b>" value="<b>paramValue1</b>"/&gt;
  ...
  &lt;Param name="<b>paramNameN</b>" value="<b>paramValueN</b>"/&gt;
&lt;/Url&gt;
&lt;Url type="application/x-suggestions+json" template="<b>suggestionURL</b>"/&gt;
&lt;moz:SearchForm&gt;<b>searchFormURL</b>&lt;/moz:SearchForm&gt;
&lt;/OpenSearchDescription&gt;
</pre>
<dl><dt> <b>ShortName</b>
</dt><dd> Nombre corto para el motor de búsqueda.
</dd></dl>
<dl><dt> <b>Description</b>
</dt><dd> Descripción del motor de búsqueda.
</dd></dl>
<dl><dt> <b>InputEncoding</b>
</dt><dd> Codificación de caracteres a emplear en los datos que se envían al motor de búsqueda. Por ejemplo, "UTF-8".
</dd></dl>
<dl><dt> <b>Image</b>
</dt><dd> Icono de 16x16 codificado en Base-64 que represente al motor de búsqueda. Puedes encontrar una utilidad para generar estos datos en: <a class="external" href="http://software.hixie.ch/utilities/cgi/data/data">The data: URI kitchen</a>.
</dd></dl>
<dl><dt> <b>Url</b>
</dt><dd> Describe la(s) URL(s) a emplear para la búsqueda.  El atributo <code>method</code> indica si se debe emplear una petición <code>GET</code> o <code>POST</code> para obtener los resultados.
</dd></dl>
<dl><dd><div class="note"><b>Nota:</b> Internet Explorer 7 no admite peticiones <code>POST</code>.</div>
</dd></dl>
<dl><dd> Firefox admite dos tipos de URL en el campo <code>type</code>:
</dd></dl>
<ul><li> <code>type="text/html"</code> se usa al especificar la URL a donde se va a enviar la petición de búsqueda.
</li><li> <code>type="application/x-suggestions+json"</code> se usa al especificar la URL de donde se van a obtener las sugerencias de búsqueda.
</li></ul>
<dl><dd> El atributo <code>template</code> indica la forma en que se construirá la URL para la consulta. Dentro de este atributo se pueden introducir plantillas que se expanden de forma dinámica; la más habitual es <code>{searchTerms}</code>, la cual se expande a los términos de búsqueda introducidos por el usuario en la barra de búsquedas. En <a class="external" href="http://www.opensearch.org/Specifications/OpenSearch/1.1/Draft_3#OpenSearch_1.1_parameters">OpenSearch 1.1 parameters</a> se describen los otros tipos admitidos.
</dd></dl>
<dl><dd> Para consultas que devuelven sugerencias de búsqueda, la URL descrita en <code>template</code> se usa para obtener una lista de sugerencias en el formato JSON (JavaScript Object Notation).  Para saber más sobre como incorporar sugerencias de búsqueda en el lado del servidor, ver <a href="es/Supporting_search_suggestions_in_search_plugins">Supporting search suggestions in search plugins</a>.
</dd></dl>
<p><img alt="Image:SearchSuggestionSample.png" src="File:es/Media_Gallery/SearchSuggestionSample.png">
</p>
<dl><dt> <b>Param</b>
</dt><dd> The parameters that need to be passed in along with the search query, as key/value pairs.  When specifying values, you can use <code>{searchTerms}</code> to insert the search terms entered by the user in the search bar.
</dd><dd><div class="note"><b>Note:</b> Internet Explorer 7 does not support this element.</div>
</dd></dl>
<dl><dt> <b>SearchForm</b>
</dt><dd> 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.
</dd><dd><div class="note"><b>Note:</b> Since this element is Firefox-specific, and not part of the OpenSearch specification, we use the "<code>moz:</code>" XML namespace prefix in the example above to ensure that other user agents that don't support this element can safely ignore it.</div>
</dd></dl>
<h2 name="Autodiscovery_of_search_plugins">Autodiscovery of search plugins</h2>
<p>A web site that offers a search plugin can advertise it so that Firefox users can easily download and install the plugin.
</p><p>To support autodiscovery, you simply need to add one line to the <code>&lt;head&gt;</code> section of your web page:
</p>
<pre class="eval">&lt;link rel="search" type="application/opensearchdescription+xml" title="<i>searchTitle</i>" href="<i>pluginURL</i>"&gt;
</pre>
<p>Replace the italicized items as explained below:
</p>
<dl><dt> <b>searchTitle</b>
</dt><dd> The name of the search to perform, such as "Search MDC" or "Yahoo! Search". This value should match your plugin file's ShortName.
</dd></dl>
<dl><dt> <b>pluginURL</b>
</dt><dd> The URL to the XML search plugin, from which the browser can download it.
</dd></dl>
<p>If your site offers multiple search plugins, you can support autodiscovery for them all.  For example:
</p>
<pre class="eval">&lt;link rel="search" type="application/opensearchdescription+xml" title="MySite: By Author" href="http://www.mysite.com/mysiteauthor.xml"&gt;
&lt;link rel="search" type="application/opensearchdescription+xml" title="MySite: By Title" href="http://www.mysite.com/mysitetitle.xml"&gt;
</pre>
<p>This way, your site can offer plugins to search both by author and by title as separate entities.
</p>
<h2 name="Troubleshooting_Tips">Troubleshooting Tips</h2>
<p>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.
</p>
<ul><li>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;amp; and tags need to be closed with a trailing slash or matching end tag.
</li><li>The <code>xmlns</code> attribute is important, without it you could get an error message indicating that "Firefox could not download the search plugin from: (URL)".
</li><li>Note that you <b>must</b> include a <code>text/html</code> URL — search plugins including only Atom or <a href="es/RSS">RSS</a> URL types (which is valid, but Firefox doesn't support) will also generate the "could not download the search plugin" error.
</li><li>Remotely fetched favicons must not be larger than 10KB (see {{template.Bug(361923)}}).
</li></ul>
<p>In addition, the search plugin service provides a logging mechanism that may be of use to plugin developers. Use <i>about:config</i> to set the pref '<code>browser.search.log</code>' to <code>true</code>. Logging information will appear in Firefox's <a href="es/Error_Console">Error Console</a> (Tools-&gt;Error Console) when search plugins are added.
</p>
<h2 name="Reference_Material">Reference Material</h2>
<ul><li><a class="external" href="http://opensearch.org/">OpenSearch Documentation</a>
</li><li>Technorati.com has a <a class="external" href="http://technorati.com/osd.xml">working osd.xml</a>
</li><li>More on Autodiscovery difficulties at bugzilla {{template.Bug(340208)}}
</li><li><a class="external" href="http://en.wikipedia.org/wiki/Data:_URI_scheme"><code>data:</code> URI scheme</a>
</li><li><a class="external" href="http://searchy.protecus.de/">Searchy</a> - <a class="external" href="http://searchy.protecus.de/en/add2.php">create</a> your own or use  <a class="external" href="http://searchy.protecus.de/en/searchbox-add-ons.php">the list of Search plugins</a>.
</li><li><a class="external" href="http://www.searchplugins.net">searchplugins.net</a> - create OpenSearch plugins for use with Firefox 2. <a class="external" href="http://www.searchplugins.net/pluginlist.aspx">List of generated search plugins</a>
</li><li><a class="external" href="http://keijisaito.info/ready2search/e/">Ready2Search</a> - create OpenSearch plugins.  <a class="external" href="http://keijisaito.info/arc/search/en_cs_r2s.htm">Customized Search through Ready2Search</a>
</li></ul>
<p><span class="comment">Interwiki link</span>
</p>{{ wiki.languages( { "ca": "ca/Creaci\u00f3_de_connectors_OpenSearch_per_al_Firefox", "en": "en/Creating_OpenSearch_plugins_for_Firefox", "fr": "fr/Cr\u00e9ation_de_plugins_OpenSearch_pour_Firefox", "ja": "ja/Creating_OpenSearch_plugins_for_Firefox" } ) }}
Revertir a esta revisión