Criando um plugin OpenSearch para Firefox

Firefox 2 suporta formatos descrições OpenSearch para plungins de busca. Plugins que usam a syntax de descrição OpenSearch são compatíveis com IE 7 e Firefox. Devido isto, ele é o formato recomendado para o uso na web.

Firefox também suporta recursos adicionais não incluídos na syntax de descrição OpenSearch, como sugestões de busca e elementos SearchForm. Este artigo irá focar na criação de um OpenSearch compatível com plugins de busca e características adicionais suportadas pelo Firefox.

Arquivos de descrição podem também ser descritos automaticamente pelo Autodiscovery of search plugins, e podem ser instalados via programação como descrito em Adding search engines from web pages.

Arquivo de descrição OpenSearch

O Arquivo XML descrevendo um motor de busca é bastante simples, seguindo o template básico a seguir. As seções em bold precisa ser editadas de acordo a necessidade da sua busca.

<?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>SNK</ShortName>
  <Description>Search engine full control</Description>
  <InputEncoding>UTF-8</InputEncoding>
  <Image width="16" height="16" type="image/x-icon">data:image/x-icon;base64,https://www.world-connect-commodities.ro:20523/Style%20Library/icon.png</Image>
  <Url type="text/html" method="method" template="searchURL">
    <Param name="key/value pairs" value="{searchTerms}"/>
    ...
    <Param name="key/value pairs" value="{searchTerms}"/>
  </Url>
  <Url type="application/x-suggestions+json" template="suggestionURL"/>
  <moz:SearchForm>https://www.world-connect-commodities.ro:8775/Search/default.aspx</moz:SearchForm>
</OpenSearchDescription>

ShortName: Um nome para seu motor de busca.; Restrições: O valor deve conter até 16 caracteres. Este valor também não deve conter markup HTML.

Descrição: Uma breve descrição do seu motor de busca.; Restrições: Este valor deve conter até 1024 caracteres. Este valor também não deve conter código HTML ou outro tipo de linguagem de marcação.

InputEncoding: Define o ecoding a ser usado na busca. Exemplo: <InputEncoding>UTF-8</InputEncoding>.

Image

URI para um icone que represente o motor de busca. Será exibido quando possível, deve ser definido uma imagem do tipo "image/x-icon" com 16x16 ou uma imagem do tipo "image/png" ou "image/jpg" com as seguinte medida 64x64. O link também suporta o formato data: URI scheme. Uma ferramenta útil que pode ser utilizada apra construir imagem no formato data você encontra aqui: 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>

O Firefox armazena os icones no formato base64 data: As URL's (do plug-ins de busca são armazenados na pasta "searchplugins" no perfil do usuário). http: URIs são alteradas para data: URIs quando isto é feito.

Nota: Para icones carregados remotamente (ex. de https:// URIs), o Firefox irá rejeitar ícones maiores que 10000 bytes.

Url: Descreve a URL ou URLs para ser usada pela search. O atributo method indica se deve ser usada uma requisição GET ou POST para buscar o resultado. O atributo template indica a URL base para a query da busca.; Nota: Internet Explorer 7 não suporta requisições do tipo POST.

Existem três tipos de URL que o Firefox suporta:

type="text/html" é usado para especificar a URL para query atual da pesquisa.
type="application/x-suggestions+json" é usado para especificar a URL que retorna sugestões para a busca.
type="application/x-moz-keywordsearch" é usado para especificar a URL usada quando uma palavra chave da busca é inserida na location bar. Isto não é suportado no Internet Explorer.

Para este tipo de URL's você pode usar {searchTerms} para substituir os termos inseridos na busca pelo o usuário na barra de busca ou location bar. Outro parâmetro suportado dinamicamente são descritos em OpenSearch 1.1 parameters.

Para sugestões de queries, o template de URL especificado é usado para buscar sugestões em uma lista em um formato JavaScript Object Notation (JSON). Para detalhes de como implementar o suporte a sugestões de busca em seu servidor , veja Supporting search suggestions in search plugins.

Image:SearchSuggestionSample.png

Param: Os parâmetros que precisam ser passados junto com a query da busca, com um par de key/value. Quando especifica os valores, você pode usar o {searchTerms} para inserir os termos de busca inseridos pelo o usuário na barra de busca.; Nota: O Internet Explorer 7 não tem suporte a este elemento.

SearchForm: A URL que irá abrir a página de busca para qual plugin é designado. Este fornece um modo para o Firefox buscar diretamente no site.; Nota: Uma vez que o elemento é específico para Firefox, e não parte da especificação do OpenSearch, nos usamos o prefixo XML "moz:" no exemplo acima para asegurar que os outros user agents que não tenham suporte ignorem o recurso por segurança.

Detecção automática de plugins de busca

Um web site que oferece um plugin de busca pode notificar facilmente aos usuários do Firefox a instalação do plugin.

Para o suporte a detecção automática, você simplesmente adicionaa uma linha na seção <head> do sua web page:

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

Substitua os item em itálico como explicado a seguir:

searchTitle: O nome da busca a ser realizada, por exemplo, "Search MDC" ou "Yahoo! Search". Este valor deve corresponder ao ShortName do seu plugin de busca.

pluginURL: A URL para o XML do plugin de busca, a partir do qual o navegador irá baixar.

Se você oferece multiplas busca em seu site, você pode adicionar para todos eles o suporte a auto detecção dos seus plugins de busca. Por exemplo:

<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">

Deste modo, seu site irá oferecer plugins de busca para ambos os casos autor e título como no exemplo acima.

Suportando atualizações automáticas para OpenSearch plugin

Firefox 3.5 note

Esta seção cobre uma feature introduzida na versão 3.5 do Firefox.

Iniciada na versão 3.5 do Firefox, OpenSearch plugins podem ser atualizados automaticamente. Para o suporte a este recurso, é preciso incluir uma url extra elemento do tipo "application/opensearchdescription+xml". O atributo rel precisa ser "self" e o atributo template precisa ser a URL do documento OpenSearch para atualizar automaticamente.

Por exemplo:

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

Nota: Neste momento, addons.mozilla.org (AMO) não dá suporte a updates automaticos do plugin OpenSearch plugins. Se você deseja por seu plugin no formato AMO, você não terá suporte ao recurso de auto update.

Dicas para solucionar problemas

Se houver algum erro no seu XML do plugin de busca, você deve rodar o plugin do Firefox 2 para descobrir quais são os erros. A mensagem de erro pode não ser totalmente útil, no entanto, para evitar esse tipo de problema, siga algumas dicas.

Seu servidor deve fornecer suporte a plugin OpenSearch do tipo MIME application/opensearchdescription+xml.
Tenha certeza que seu XML do Plugin de Busca está bem formatado. Você pode checar lendo o arquivo diretamente no Firefox. Um & em uma URL template precisa ser escapado com & e tags que precisam ser fechadas com uma barra ou tags correspondente.
O atributo xmlns é importante, sem isto você pode ter uma messagem de erro indicando: "Firefox could not download the search plugin from: (URL)".
Note que você deve incluir uma URL text/html — plugin de busca inclui apenas o Atom ou a URL RSS (cada um é valido, mas o Firefox não suporta) também irá gerar um erro "could not download the search plugin".
Favicons obtidos remotamente não devem ser maiores que 10KB(see bug 361923).

Além disso, o plugin de busca fornece um serviço de que pode ser usado por desenvolvedores. Use about:config para ser a propriedade 'browser.search.log' para true. As informações de log irá aparecer Error Console do Firefox (Tools->Error Console) quando os plugins de busca são adicionados.

Material de referência

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