Criando plugins OpenSearch para o Firefox

OpenSearch

Firefox 2 suporta o formato de descrição OpenSearch para plugins de busca. Plugins que usam a OpenSearch description syntax são compativeis com IE 7 e Firefox. Por causa disso, ele é o formato recomendado para uso na web.

Firefox também suporta capacidades adicionais de busca não incluidos na OpenSearch description syntax, tais como as sugestões de busca e o elemento SearchForm. Este artigo terá fóco na criação de plugins de busca compativeis com a sintaxe OpenSearch e com suporte a essas caracteristicas específicas do Firefox.

O arquivo de descrição OpenSearch também pode ser reconhecido automaticamente pelo browser como descrito em Autodiscovery of search plugins, e pode ser instalado atravéz de programação como descrito em Adding search engines from web pages.

Arquivo de descrição OpenSearch

O arquivo XML descrevendo um motor de busca é, na verdade, muito simples, sequindo o template abaixo. As seções em negrito devem ser customizadas de acordo com as necessidades específicas para o plugin do motor de busca que você está escrevendo.

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/"
                       xmlns:moz="http://www.mozilla.org/2006/browser/search/">
<ShortName>Nome do motor</ShortName>
<Description>Descrição do motor</Description>
<InputEncoding>Codificação de entrada</InputEncoding>
<Image width="16" height="16">data:image/x-icon;base64,Dados da imagem</Image>
<Url type="text/html" method="método" template="URL de busca">
  <Param name="Nome do parametro 1" value="Valor do parametro 1"/>
  ...
  <Param name="Nome do parametro N" value="Valor do parametro N"/>
</Url>
<Url type="application/x-suggestions+json" template="URL de Sugestões"/>
<moz:SearchForm>URL do form de procura</moz:SearchForm>
</OpenSearchDescription>
Nome do motor
Um nome curto para o motor de busca.
Descrição do motor
Uma breve descrição do motor de busca.
Codificação de entrada
A codificação que será usada na entrada de dados do motor de busca. Ex:UTF8
Dados da imagem
Um icone de representação para o motor de busca de tamanho 16x16 e codificado em Base-64. Uma ferramente muito boa que você pode usar para construir os dados para colocar aqui pode ser encontrado aqui: The data: URI kitchen.
Url
Descreve a URL ou URLs para usar na busca. O atributo method indica quando usar requisição GET ou POST para buscar os resultados. O atributo template indica a URL base para a pesquisa.
Nota: Internet Explorer 7 não suporta requisições via POST.
Existem dois tipos de URL que o Firefox suporta:
  • type="text/html" é usado para especificar a URL da pesquisa atual em si.
  • type="application/x-suggestions+json" é usado para especiicar a URL em pesquisas com sugestões.
Para qualquer um desses tipos de URL, você pode usar o {searchTerms} para substituir os termos de busca colocados pelo usuário na barra de busca. Outros parâmetros dinâmicos de busca suportados estão descritos em OpenSearch 1.1 parameters.
Para buscas com sugestões, o template de URL especificado é usado para trazer uma lista de sugestões no formato JavaScript Object Notation (JSON). Para detalhes de como implementear o suporte a sugestões de busca no servidor, olhe Supporting search suggestions in search plugins.

Image:SearchSuggestionSample.png

Parametros
São os parametros que precisam ser passados juntamente com os dados da consulta, em pares Chave/Valor. Quando especificar valores, você pode usar o {searchTerms} para inserir os termos de busca colocados pelo usuário na barra de busca.
Nota: Internet Explorer 7 não suporta este elemento.
Forme de Busca
É a URL da pagina de busca do site para qual o plugin de busca foi desenvolvido. Esta pagina será aberta quanda não forem informados termos na barra de busca. Isso provê um caminho para que os usuarios do firefox visitem o site diretamente.
Nota: Sendo um elemento específico do Firefox, e não parte da especificação OpenSearch, nós usaremos o prefixo de nome XML "moz:" como no exemplo acima, para assegurar que outros navegadores que não suportam este elemento possam ignora-lo com segurança.

Descobrimento automatico de plugins de busca

Um site que oferece um plugin de busca pode anuncia-lo de forma que os usuarios do Firefox possam facilmente baixar e instalar o plugin.

Para prover o Descobrimento automatico, você deve simplesmete adicionar uma linha de codigo na seção <head> de sua pagina web:

<link rel="search" type="application/opensearchdescription+xml" title="Titulo do buscador" href="URL do plugin">

Substitua os itens em italico como explicado abaixo:

Titulo do buscador
O nome do buscador, como "Search MDC" ou "Yahoo! Search". Este valor deve corresponder ao nome do motor contido no arquivo do plugin.
URL do plugin
A URL para o arquivo XML do plugin de busca, de onde o browser poderá baixa-lo.

Se o seu site oferece multiplos plugins de busca, você poderá dar suporte ao descobrimento automatico a todos eles. Por exemplo:

<link rel="search" type="application/opensearchdescription+xml" title="Meu Site: Por Autor" href="http://www.meusite.com/meusiteautor.xml">
<link rel="search" type="application/opensearchdescription+xml" title="Meu Site: Por Titulo" href="http://www.meusite.com/meusitetitulo.xml">

Desta maneira, seu site pode oferecer plugins de busca tanto para autores quanto para titulos como entidades separadas.

Solucionando Problemas

Se existe um erro em seu código XML do plugin de busca, você pode acessar os erros quando estiver adicionando um plugin descoberto no Firefox 2. A mensagem de erro pode não lhe ajudar completamente, mas, seguir as dicas abaixo deve ajudar você a encontrar o problema.

  • Certifique-se que o XML do seu Plugin de Busca está bem formatado. Você pode checar isto carregando o arquivo diretamente no Firefox. & no template URL deve ser usado como &amp; e tags devem ser fechadas com uma barra ou tag final correspondente..
<shortName /> 
<shortName>Google search</shortName>
  • O atributo xmlns é importante, sem ele você pode obter uma mensagem de erro indicando que "O Firefox não pôde baixar o plugin de busca de: (URL)".
  • Note que você deve incluir uma URL text/html — plugins de busca incluindo somente os tipos de URL Atom ou RSS (que são válidos, mas o Firefox não suporta) também gerarão o erro "não foi possível baixar o plugin de busca".
  • Favicons buscados remotamente não devem ser maiores do que 10KB (veja bug 361923).

Além disso, o serviço de plugin de busca proporciona um mecanismo de log que pode ser útil para desenvolvedores de plugins. Use about:config para configurar a preferência 'browser.search.log' para true (verdadeira). Informações do log aparecerão no Console de Erros do Firefox (Error Console)(Ferramentas -> Console de Erros) quando os plugins de busca forem adicionados.

Material de Referência

Interwiki link

Document Tags and Contributors

Contributors to this page: Verruckt, tregagnon, Rodrigoknascimento
Last updated by: tregagnon,