Construir uma Extensão

Introdução

Este tutorial lhe dará uma visão bem básica dos passos para construir uma extensão - que adiciona um item na barra de status do Firefox contendo o texto "Hello, World!"

Nota Este tutorial é voltado para o desenvolvimento de extensões para Firefox 1.5 ou 2.0. Existem outros tutoriais para o desenvolvimento extensões para versões mais antigas do Firefox.

Ajustando o Ambiente de Desenvolvimento

As extensões são empacotadas e distribuídas em arquivos ZIP, ou Bundles, arquivos com a extensão xpi (pronunciado “zippy”). A disposição do conteúdo dentro do arquivo XPI é assim:

extension.xpi:
              /install.rdf                   
              /components/*  
              /components/cmdline.js                   
              /defaults/
              /defaults/preferences/*.js     
              /plugins/*                        
              /chrome/
              /chrome.manifest                
              /chrome/icons/default/*
              /chrome/content/

Por isso, é mais fácil dispor seus arquivos de código de uma forma similar, a menos que você queira escrever algum tipo de Makefile ou shell script para empacotar e fechar todos os seus arquivos. Mesmo que esteja preparado para fazer isso, testar é muito mais simples se você dispuser seus arquivos desta maneira, devido a uma característica do Sistema de Add-on proporcionado a partir do Firefox 1.5.

Assim, vamos começar. Crie uma pasta para sua extensão em algum lugar do disco rígido, por exemplo C:\extensions\myExtension\ ou ~/extensions/myExtension/. Dentro desta pasta crie outra pasta chamada chrome, e dentro da pasta chrome crie outra pasta chamada content. (Em sistemas como o Unix você pode normalmente criar todos os três diretórios somente rodando mkdir -p chrome/content dentro do diretório root (raiz) da extensão.)

Dentro da raiz da sua pasta da extensão, ao lado da pasta chrome, crie dois novos arquivos de texto vazios, um chamado chrome.manifest e outro chamado install.rdf.

Mais ajuda no desenvolvimento de extensões pode ser encontrada na página Mozillazine Knowledge Base.

Criando o manifesto de instalação

Abra o arquivo chamado install.rdf que você criou no topo da pasta da sua extensão e coloque isto nele:

<?xml version="1.0"?>

<RDF xmlns="https://www.w3.org/1999/02/22-rdf-syntax-ns#"
     xmlns:em="https://www.mozilla.org/2004/em-rdf#">

  <Description about="urn:mozilla:install-manifest">
    <em:id>[email protected]</em:id>
    <em:version>1.0</em:version>
    <em:type>2</em:type>
   
    <!-- Target Application this extension can install into, 
         with minimum and maximum supported versions. --> 
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
        <em:minVersion>1.5</em:minVersion>
        <em:maxVersion>2.0.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
   
    <!-- Front End MetaData -->
    <em:name>Amostra!</em:name>
    <em:description>Uma extensão de teste</em:description>
    <em:creator>Seu Nome Aqui</em:creator>
    <em:homepageURL>https://www.foo.com/</em:homepageURL>
  </Description>      
</RDF>

[email protected] - o ID da extensão. Este é um valor que você usa para identificar sua extensão em formato de endereço de e-mail (note que isto não precisa ser o seu e-mail). Faça isto único. Você pode também usar um GUID. NOTA: Este parametro PRECISA estar no formato de um endereço de e-mail, no entanto NÃO precisa ser um e-mail válido.
Especifique <em:type>2</em:type> -- o 2 declara que isto instala uma extensão. Se você for instalar um tema o número será 4 (veja Install Manifests#type para outros tipos de código).
{ec8030f7-c20a-464f-9b0e-13a3a9e97384} - ID de aplicação Firefox.
1.5 - a versão mínima do Firefox que você está dizendo que esta extensão poderá trabalhar. Coloque isto como a versão mínima, você cometerá e testará bugs (problemas) com isso.
2.0.0.* - a versão máxima do Firefox que você está dizendo que esta extensão poderá trabalhar. Coloque isto com a versão mais nova disponível atualmente! Neste caso, "2.0.0.*" indica que a extensão trabalha com versões do Firefox 2.0.0.0 até 2.0.0.x.

Extensões desenhadas para trabalhar com o Firefox 1.5.0.x devem ser colocadas no máximo com a versão "1.5.0.*".

Veja Install Manifests para uma lista completa das propriedades requeridas e opcionais.

Salve o arquivo.

Estendendo o navegador com XUL

A interface do usuário do Firefox é escrita em XUL e JavaScript. XUL é uma gramática XML que proporciona widgets como botões, menus, barras de ferramentas, árvores, etc. As ações do usuário são limitadas à funcionalidade usando JavaScript.

Para extender o navegador, nós modificamos partes da UI do navegador adicionando ou modificando widgets. Nós adicionamos widgets inserindo novos elementos DOM XUL na janela do navegador, e os modificamos utilizando scripts e anexando manipuladores de evento.

O navegador é implementado por um arquivo XUL chamado browser.xul ($FIREFOX_INSTALL_DIR/chrome/browser.jar que contém content/browser/browser.xul). Em browser.xul nós podemos encontrar a barra de status, semelhante a isso:

<statusbar id="status-bar">
 ... <statusbarpanel>s ...
</statusbar>

<statusbar id="status-bar"> é o "ponto de fusão" para a sobreposição XUL (XUL Overlay).

Sobreposição (overlay) XUL

XUL Overlays é um modo de anexar outras widgets da UI a um documento XUL durante a execução. Um Overlay XUL é um arquivo .xul que especifica fragmentos de XUL para inserir em pontos específicos de junção dentro de um documento "master". Estes fragmentos podem especificar widgets para serem inseridas, removidas ou modificadas.

Exemplo de Documento de Sobreposição XUL

<?xml version="1.0"?>
<overlay id="sample" 
         xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
 <statusbar id="status-bar">
  <statusbarpanel id="my-panel" label="Hello, World"/>
 </statusbar>
</overlay>

A <statusbar> chamada status-bar especifica o "ponto de junção" dentro da janela do navegador a que nós queremos anexar.

O sub-item de <statusbarpanel> é um novo widget que nós queremos para inserir dentro do ponto de junção.

Pegue esta amostra de código acima e salve-a em um arquivo chamado sample.xul dentro da pasta chrome/content que você criou.

Para mais informaçõs sobre junção de widgets e modificação da interface de usuário usando Overlays, veja abaixo.

URLs Chrome

Arquivos XUL são parte do "Chrome Packages" - pacotes dos componentes da interface de usuário que são carregados via URLs chrome://. Melhor que carregar o navegador pelo disco usando um URL file:// (a localização do Firefox no sistema pode mudar de plataforma para plataforma e sistema para sistema), desenvolvedores Mozilla surgiram com uma solução para criar URLs para conteúdo XUL em que a aplicação instalada sabe como fazer.

A janela do navegador é: chrome://browser/content/browser.xul. Tente digitar esta URL na barra de localização do Firefox!

Chrome URLs consistem em diversos componentes:

Primeiramente, o esquema URL (chrome) que diz à biblioteca de rede do Firefox que isto é um Chrome URL. Isto indica que o conteúdo da URL deve ser manipulado como um (chrome). Compare (chrome) a (http) que diz ao Firefox para tratar a URL como uma página da web.
Secundariamente, um nome de pacote (no exemplo acima, browser) que indentifica o pacote dos componentes da interface de usuário. Isto deve ser único para sua aplicação sempre que possível para evitar colisões entre extensões.
Terciariamente, o tipo de dados é requisitado. Existem três tipos: content (XUL, JavaScript, XBL bindings, etc. que formam a estrutura e o comportamento de uma aplicação UI), locale (DTD, arquivos .properties, etc. que contêm strings para as localizações UI), e skin (CSS e imagens que formam o tema da UI)
Finalmente, o trajeto de um arquivo para carregar.

Então, chrome://foo/skin/bar.png carrega o arquivo bar.png do tema de foo na seção skin.

Quando você carrega conteúdo usando um Chrome URL, Firefox usa o Registro Chrome para traduzir estas URLs no atual arquivo de código no disco (ou em pacotes JAR).

Criando um Manifesto Chrome

Para mais informações sobre Manifestos Chrome e as propriedades que eles suportam, veja a referência Chrome Manifest.

Abra o arquivo chamado chrome.manifest que você criou ao lado do diretório chrome na raiz da pasta de código da sua extensão.

Adicione este código:

content     sample    chrome/content/

(Não se esqueça da barra, "/"! Sem ela, a extensão não será registrada.) Nota: Tenha certeza de ter digitado tudo em letras minúsculas para o nome do pacote ("sample") no Firefox/Thunderbird 1.5 não há suporte à letras maiúsculas. Aparentemente haverá na versão 2.

Isto especifica o:

tipo do material dentro do pacote chrome
nome do pacote chrome
localização dos arquivos do pacote chrome

Então, esta linha diz que para o pacote chrome sample, nós podemos achar estes arquivos content (de conteúdo) na localização chrome/content onde está o caminho relativo à localização do chrome.manifest.

Note que os arquivos de conteúdo, localização e pele precisam estar no interior das pastas chamadas content (conteúdo), locale (localização) e skin (pele) dentro do subdiretório chrome.

Salve o arquivo. Quando você rodar o Firefox com sua extensão, (depois neste tutorial), isto irá registrar o pacote chrome.

Registrando uma Sobreposição

Você precisa do Firefox para fundir da sua sobreposição com a janela do navegador sempre que ela for exibida. Então adicione esta linha ao seu arquivo chrome.manifest:

overlay chrome://browser/content/browser.xul chrome://sample/content/sample.xul

Isto dirá ao Firefox para fundir sample.xul em browser.xul quando browser.xul for carregado.

Teste

Primeiro, nós precisamos falar ao Firefox sobre a sua extensão. Nos velhos e maus dias do Firefox 1.0, isto significava empacotar sua extensão como um XPI e instalar através da interface de usuário, na qual havia uma dificuldade real. Agora é muito mais simples.

Abra sua Profile Folder
Abra a pasta extensions (crie-a se ela não existir)
Crie um novo arquivo de texto, e coloque o caminho para a pasta da extensão dentro, e.g. C:\extensions\myExtension\ ou ~/extensions/myExtension. Salve o arquivo com o id da sua extensão como seu nome, e.g. [email protected].

Agora você está pronto para testar sua extensão!

Inicie o Firefox. O Firefox irá detectar o link para o diretório da sua extensão e instalará a extensão. Quando a janela do navegador aparecer você poderá ver o texto "Hello, World!" ao lado direito do painel da barra de estado.

Você pode agora retornar e fazer mudanças no arquivo .xul, fechar e reiniciar o Firefox, e elas aparecerão. Isto realmente não combina com a extensão descrita e confunde as pessoas. -Nickolay CENTER> Image:Helloworld_tools_menu.PNG Image:Helloworld_extensions_wnd.PNG </CENTER

Pacote

Agora que sua extensão trabalha, você pode empacotá-la (package) para distribuição e instalação.

Empacote o conteúdo da pasta da extensão (não a pasta da extensão), e renomeie o arquivo empacotado para ter uma extensão .xpi. No Windows XP, você pode fazer isto facilmente selecionando todos os arquivos e sub pastas na pasta da sua extensão, com um clique do botão direito e a escolha "Enviar para -> Pasta Comprimida". Um arquivo .zip será criado para você. Somente renomeie-o e pronto!

No Mac OS X, você pode com um clique do botão direito sobre a pasta da extensão escolher "Criar Arquivo de..." para fazer o arquivo .zip. No entanto, desde que o Mac OS X adiciona arquivos escondidos à pastas para ordenar os metadados do arquivo, você deve em vez disso usar o Terminal, deletar os arquivos escondidos (cujos nomes começam com um período), e então usar o comando zip na linha de comando para criar o arquivo .zip.

No Linux, você pode do mesmo modo usar a ferramenta Zip pela linha de comando.

Se você tem a extensão 'Extension Builder' instalada ela pode compilar o arquivo .xpi para você (Ferramentas -> Desenvolvimento de Extensões -> Construtor de Extensões). Meramente navegue até o diretório onde sua extensão está (install.rdf etc.), e clique no botão Construir Extensão. Esta extensão possui várias ferramentas para tornar o desenvolvimento mais fácil.

Agora atualize o arquivo .xpi no seu servidor, assegurando-se que ele serve como application/x-xpinstall. Você pode ligar para isto e permitir as pessoas baixarem e instalarem-na no Firefox. Para os propósitos de somente testar nosso arquivo .xpi nós podemos apenas arrastá-lo até a janela de extensões via Ferramentas -> Complementos -> Extensões.

Usando addons.mozilla.org

Mozilla Update é um site de distribuição onde você pode hospedar sua extensão de graça. Sua extensão irá ser hospedada na rede de espelho Mozilla para garantir seu download mesmo quando se tornar mais popular. O site Mozilla também proporciona aos usuários uma instalação simples, e colocará automaticamente suas versões mais novas disponíveis para os usuários das suas versões já existentes quando você atualizá-las. Em adição o Mozilla Update permite aos usuários comentar e proporcionar avaliações da sua extensão. Isto é altamente recomendado se você usa o Mozilla Update para distribuir suas extensões!

Visite https://addons.mozilla.org/developers/ para criar uma conta e começar a distribuir suas extensões!

Nota: Sua extensão será passada rapidamente e mais baixada, se você tiver uma boa descrição e algumas fotos da extensão em ação.

Registrando Extensões no Registro do Windows

No Windows, informação sobre extensões pode ser adicionada ao registro, e as extensões serão automaticamente "colhidas" na próxima vez que a aplicação iniciar. Isto permite que os instaladores de aplicação adicionem facilmente os ganchos de integração como extensões. Veja Adding Extensions using the Windows Registry para mais informações.

Mais sobre Sobreposições XUL

Além de adicionar widgets UI ao ponto de fusão, você pode usar fragmentos XUL dentro da sobreposição para:

Modificar atributos no ponto de fusão, e.g. <statusbar id="status-bar" hidden="true"/> (esconde a barra de estado)
Remove o ponto de fusão do documento mestre, e.g. <statusbar id="status-bar" removeelement="true"/>
Controla a posição das widgets inseridas:

<statusbarpanel position="1" .../>

<statusbarpanel insertbefore="other-id" .../>

<statusbarpanel insertafter="other-id" .../>

Criando Novos Componentes na Interface de Usuário

Você pode criar suas próprias janelas e caixas de diálogo em arquivos .xul separados, proporcionar funcionalidades pela implementação de ações de usuário em arquivos .js, usando métodos DOM para manipular widgets UI. Você pode usar regras de estilo em arquivos .css para anexar imagens, configurar cores, etc.

Veja a documentação XUL para mais recursos para desenvolvedores XUL.

Arquivos Padrão

Arquivos padrão que você usa para escalar um perfil de usuário que deve ser colocado em defaults/ sob a raiz da pasta da sua extensão. Preferências padrão em arquivos .js devem ser armazenadas em defaults/preferences/ — quando você as coloca aqui elas são automaticamente carregadas pelas preferências do sistema do Firefox quando ele é iniciado, então você pode acessá-las usando o Preferences API.

Componentes XPCOM

O Firefox suporta componentes XPCOM nas extensões. Você pode criar seus próprios componentes facilmente em JavaScript ou em C++ (usando o Gecko SDK).

Coloque todos os seus arquivos .js ou .dll no diretório components — eles são automaticamente registrados na primeira vez que o Firefox rodar depois que sua extensão for instalada.

Para mais informações, veja os livros How to Build an XPCOM Component in Javascript e Creating XPCOM Components.

Aplicação de Linha de Comando

Um dos possíveis usos dos componentes customizados XPCOM é adicionar um manipulador de linha de comando para o Firefox ou Thunderbird. Você pode usar esta técnica para rodar sua extensão como uma aplicação:

 firefox.exe -myapp

Devo mover as partes úteis disto para a página Command Line. -Nickolay Isto é feito adicionando um componente que contém a função... function NSGetModule(comMgr, fileSpec) { return myAppHandlerModule; } Esta função roda pelo Firefox cada vez que ele é iniciado. O Firefox registra o myAppHandlerModule's chamando-o 'registerSelf()'. Então isto obtém a fábrica de manipulador myAppHandlerModule's via 'getClassObject()'. A fábrica de manipulador é usada para criar a manipulação usando isto 'createInstance(). Finalmente, a manipulação 'handle(cmdline)' processa a linha de comando cmdline's handleFlagWithParam() e handleFlag(). Veja Chrome: Command Line e a discussão no fórum para detalhes (em inglês).

Localização

Para suportar mais que uma linguagem, você deve separar as strings do seu conteúdo usando entities e string bundles. É muito mais fácil fazer isto se você estiver desenvolvendo sua extensão do que retornar fazer isto mais tarde!

Informação de localização é armazenada no diretório local (locale) da extensão. Por exemplo, para adicionar um local à nossa extensão de amostra, crie um diretório chamado "locale" em chrome (onde o diretório "content está localizado) e adicione a linha seguinte ao arquivo chrome.manifest:

locale sample sampleLocale chrome/locale/

Para criar valores atributos localizáveis em XUL, você colocar os valores em um arquivo .ent (ou um .dtd), o qual deve ser colocado no diretório locale e ser como este:

<!ENTITY  button.label     "Click Me!">
<!ENTITY  button.accesskey "C">

E depois incluí-lo no topo do seu documento XUL (mas embaixo de '<?xml version"1.0"?>') assim:

<!DOCTYPE window SYSTEM "chrome://packagename/locale/filename.ent">

Onde window é o valor localName do elemento raiz do documento XUL, e o valor da propriedade SYSTEM é o chrome URL para o arquivo de entidade. Para a nossa extensão de amostra, o elemento raiz é overlay.

Para usar as entidades, modifique seu XUL para isto:

<button label="&button.label;" accesskey="&button.accesskey;"/>

O Registro Chrome assegurará que o arquivo da entidade seja carregado do pacote de localização correspondente ao local selecionado.

Para strings que você usa no script, crie um arquivo .properties, um arquivo de texto que tem uma string em cada linha, neste formato:

key=value

e então use as etiquetas en:nsIStringBundleService/en:nsIStringBundle ou <stringbundle> para carregar os valores dentro do script.

Entendendo o navegador

Use o DOM Inspector (não é parte da instalação padrão do Firefox, você precisa reinstalá-lo pelo caminho da instalação customizada e escolher Ferramentas de Desenvolvedor se não houver um item "DOM Inspector" no menu de Ferramentas do seu navegador) para inspecionar a janela do navegador ou qualquer outra janela XUL que você precisar extendê-la.

Use o botão esquerdo do mouse para achar o nó no topo esquerdo da barra de ferramentas do DOM Inspector, clicando em um nó ele é selecionado e exibe o XUL na janela ao lado. Quando você faz isto a visão da árvore de hierarquia do DOM Inspector irá pular para o nó que você clicou.

Use o painel do lado direito do DOM Inspector para descobrir pontos de fusão com ids que você pode usar para inserir seus elementos de sobreposição. Se você não pode descobrir um elemento com um id que você pode fundir, você pode necessitar anexar um script em sua sobreposição e inserir seus elementos quando o evento load for exibido na janela mestre XUL.

Depurando extensões

Ferramentas Analíticas para Depurar

O DOM Inspector — inspeciona atributos, estrutura DOM, regras no estilo CSS que estão em efeito (e.g. descubra porque suas regras de estilo não aparecem trabalhando por um elemento — uma ferramenta inestimável!)
Venkman — configura pontos de parada em JavaScript e inspeciona pilhas de chamadas.
arguments.callee.caller em JavaScript — acessa a função de pilhas de chamadas.

Depuração printf

Rode o Firefox com -console na linha de comando e use dump("string") (veja o link para detalhes).
Use en:nsIConsoleService para logar ao console JavaScript.

Depuração avançada

Rode uma depuração do Firefox construída e configure pontos de parada no próprio Firefox ou em componentes C++. Para o desenvolvedor com experiência, este é freqüentemente a maneira mais rápida de diagnosticar o problema. Veja Build Documentation e Desenvolvimento Mozilla para mais informações.
Veja Debugging a XULRunner Application para mais tipos de ajuda.

Começo rápido

Você pode usar a ferramenta online Extension Wizard para gerar uma simples extensão para trabalhar junto.

Um Hello World extension similar ao que você pode gerar com o Extension Wizard é explicado linha por linha em outro tutorial do MozillaZine Knowledge Base.