Introdução
Um Manifesto de Instalação é o arquivo que o Gerenciador de Complementos ativa os usos do aplicativo XUL para determinar informações sobre um complemento enquanto está sendo instalado. Ele contém metadados identificando o complemento, proporcionando informações sobre quem o criou, onde podem ser encontradas mais informações sobre ele, quais versões do aplicativo são compatíveis com esta, como esta pode ser atualizada, e assim por diante.
O formato do Manifesto de Instalação é RDF/XML.
O arquivo deve ter o nome de install.rdf e estar no nível mais elevado de um arquivo XPI de complemento.
Disposição
A disposição básica de um Manifesto de Instalação é assim:
<?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"> <!-- properties --> </Description> </RDF>
Algumas propriedades são necessárias, algumas são opcionais. Algumas tem strings com valores simples, algumas são complexos recursos.
Referência necessária da propriedade
Seu Manifesto de Instalação deve especificar estas propriedades corretamente, caso contrário seu complemento poderá não instalar.
id (identificação)
O id da extensão, o qual é um:
- GUID (gerado usando "guidgen" no sistema Windows ou "uuidgen" no sistema Unix) (Firefox 1.0)
- Fifefox 1.5 e mais recentes: Uma string formatada como:
O último formato é significantemente mais fácil de gerar e manipular. O Firefox 1.5 checará para assegurar que seu id caia em um formato ou outro e irá recusar-se a instalar complementos que tenham ids malformados.
Exemplos
<em:id>[email protected]</em:id> <em:id>{daf44bf7-a45e-4450-979c-91cf07434c3d}</em:id>
version (versão)
Uma string de versão identifica a versão do complemento fornecido.
Para o Firefox/Thunderbird 1.0, o formado deve ser conforme as regras especificadas em en:Extension Versioning, Update and Compatibility. Para Firefox/Thunderbird 1.5, veja en:Toolkit version format.
Exemplos
<em:version>2.0</em:version> <em:version>1.0.2</em:version> <em:version>0.4.1.2005090112</em:version>
Firefox 1.5 / XULRunner 1.8 - complementos que não utilizam um formato de versão válida não serão instalados. O formato da versão é diferente, embora seja compatível com 1.0 mais antigas.
Para complementos hospedados em addons.mozilla.org — o site de atualizações Mozilla pode re-empacotar seu complemento e corrigir ou rejeitar strings de versão malformadas.
type (tipo)
Um valor inteiro representando o tipo do complemento.
| 2 | Extensões |
| 4 | Temas |
| 8 | Locais |
| 16 | Plugins |
| 32 | Multiple Item Package |
Exemplos
<em:type>2</em:type>
Firefox 1.5 Esta propriedade foi adicionada ao Firefox 1.5, e é somente necessário para complementos que não sejam Extensões e Temas.
targetApplication (alvo do aplicativo)
Um objeto especificando um aplicativo marcado por este complemento. Este meio que o complemento irá trabalhar com o aplicativo identificado pela propriedade id (<em:id>) especificado (para uma lista compreensível de IDs de aplicativos veja "Valid App Versions for Addon Developers" em Mozilla Addons FAQ), da versão mínima (<em:minVersion>) subindo e incluindo a versão máxima (<em:maxVersion>). Estas strings da versão são formatadas do mesmo modo como version property e serão comparados à versão do aplicativo; isto permite ao autor da extensão especificar quais as versões do Firefox e extensões foram testadas com.
Nota: O Firefox 1.0-1.0.6 todo tem uma versão de aplicativo de 1.0. Atualizações de segurança e estabilidade do Firefox 1.5 têm versão do aplicativo 1.5.0.1, 1.5.0.2, etc. Extensões compatíveis com o Firefox ou Thunderbird 1.5 devem especificar uma maxVersion de 1.5.0.*, de modo que são automaticamente compatíveis com atualizações de segurança e estabilidade.
Extensões compatíveis com o Firefox 2 devem especificar uma maxVersion de 2.0.0.*
O Manifesto de Instalação deve especificar ao menos um destes objetos, e pode especificar mais se os alvos múltiplos da aplicação do complemento suportarem o Gerenciador de Complementos (e.g. Firefox e Thunderbird)
Exemplos
<em:targetApplication>
<Description>
<em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> Firefox
<em:minVersion>1.5</em:minVersion>
<em:maxVersion>3.0.*</em:maxVersion>
</Description>
</em:targetApplication>
name (nome)
O nome do complemento — entendido por exibir o UI.
Exemplos
<em:name>My Extension</em:name>
Referência de propriedade opcional
Você pode necessitar fornecer estas propriedades, dependendo das capaciadades do seu complemento.
description (descrição)
Uma pequena descrição do complemento &mdash para exibição na interface de usuário. Esta descrição deve caber em uma curta linha de texto.
Exemplos
<em:description>Ferramentas avançadas de rodapé.</em:description>
creator (criador)
O nome do criador/principal desenvolvedor &mdash para exibição na interface de usuário.
Exemplos
<em:creator>John Doe</em:creator>
or
<em:creator>CoolExtension Team</em:creator>
developer (desenvolvedor)
Os nomes dos co-desenvolvedores. Você pode especificar mais de um valor para especificar múltiplos desenvolvedores. Novo no Firefox 2.0
Exemplos
<em:developer>Jane Doe</em:developer> <em:developer>Koos van der Merwe</em:developer>
translator (tradutor)
Os nomes dos tradutores. Você pode especificar mais de um valor para especificar múltiplos tradutores. Novo no Firefox 2.0
Exemplos
<em:translator>Janez Novak</em:translator> <em:translator>Kari Nordmann</em:translator>
contributor (contribuidor)
Os nomes de contribuidores adicionais. Você pode especificar mais de um valor para especificar múltiplos contribuidores.
Exemplos
<em:contributor>John Doe</em:contributor> <em:contributor>John Doe</em:contributor> <em:contributor>Jane Doe</em:contributor> <em:contributor>Elvis Presley</em:contributor>
homepageURL (página principal da URL)
Um link para a página principal do complemento &mdash para exibir na inteface de usuário.
Exemplos
<em:homepageURL>https://www.foo.com/</em:homepageURL>
updateURL (URL de atualização)
Um link para um arquivo customizado de Manifesto de Atualização que especifique atualizações disponíveis para o complemento. O formato é descrito abaixo. Se habilitado, o Gerenciador de Complementos periodicamente checará com o arquivo de Manifesto para determinar se novas versões estão disponíveis.
Seu servidor deve enviar este arquivo como text/rdf ou o checador de atualizações não irá trabalhar. text/xml também parece trabalhar (projetos em mozdev.org)
O Gerenciador de Complementos irá substituir os seguintes valores neste URL em casos de você querer gerar a resposta RDF dinamicamente, tal como usar PHP ou CGI:
%REQ_VERSION% |
A versão requisitada. Atualmente 1 |
%ITEM_ID% |
O id do complemento que terá de atualizar |
%ITEM_VERSION% |
A version (versão) do complemento que terá de atualizar |
%ITEM_MAXAPPVERSION% |
A maxVersion (versão máxima) do objeto targetApplication (alvo de aplicação) correspondente à aplicação atual para o complemento ser atualizado. |
%APP_ID% |
O id atual da aplicação |
%APP_VERSION% |
A version (versão) atual aplicação |
%APP_OS% |
O valor de OS_TARGET do sistema de construção do Firefox, identificando o sistema operacional a ser usado. Novo no Firefox 1.5 |
%APP_ABI% |
O valor de TARGET_XPCOM_ABI do sistema de construção do Firefox, identificando o compilador/combinação de arquitetura usada para compilar a atual aplicação. Novo no Firefox 1.5 |
Exemplos
<em:updateURL>https://www.foo.com/update.cgi?id=%ITEM_ID%&version=%ITEM_VERSION%</em:updateURL> <em:updateURL>https://www.foo.com/extension/windows.rdf</em:updateURL>
Para complementos hospedados em addons.mozilla.org: Você não pode especificar a propriedade de URL de atualização. Por padrão, aplicativos Mozilla usando o Gerenciador de Complementos (tal como o Firefox e o Thunderbird) enviaram requerimentos de atualização para addons.mozilla.org usando o serviço web padrão. Toda a vez que você atualiza para uma nova versão do seu complemento ou muda seus parâmetros de compatibilidade através da interface do autor, seu Manifesto de Atualização será gerado automaticamente.
Formato do Manifesto de Atualização: O Manifesto de Atualização é uma fonte de dados RDF/XML. Para exemplos de um Manifesto de Atualização, veja Extension Versioning, Update and Compatibility e en:Enabling Extension Updates (external).
optionsURL (URL de opções)
A URL chrome:// da caixa de diálogo das opções da extensão. Isto é utilizável somente para extensões. Se esta propriedade é especificada, quando a extensão é selecionada na lista de Extensões, o botão de Opções é habilitado e mostrará isto.
Exemplos
<em:optionsURL>chrome://myext/content/options.xul</em:optionsURL>
aboutURL (URL sobre)
A URL chrome:// da caixa de diálogo de opções da extensão. Isto é utilizável somente para extensões. Se esta propriedade é especificada, quando a extensão é selecionada na lista de Extensões, o link Sobre... no menu de contexto da extensão exibirá este diálogo, antes que o padrão.
Exemplos
<em:aboutURL>chrome://myext/content/about.xul</em:aboutURL>
iconURL (URL de ícones)
Um URL chrome:// para um ícone 32x32 para exibir na lista de complementos. Se esta propriedade não é especificada um ícone padrão é utilizado.
<em:iconURL>chrome://myext/skin/icon.png</em:iconURL>
Nota: Para o exemplo acima trabalhar você também terá que adicionar uma linha skin package ao seu arquivo chrome.manifest. Veja Registro Chrome. Alternativamente você pode colocar seu ícone no diretório especificado na linha do seu content package.
hidden (oculto)
Um valor booleano que pode ser true (verdadeiro) faz que o complemento não apareça na lista de complementos, proporcionando um complemento que é instalado em uma área de acesso restrito (então ela não trabalhará para complementos instalados no perfil). Isto é para empacotar ganchos de integração às aplicações maiores onde ter uma entrada na lista de Extensões não faz sentido.
Exemplos
<em:hidden>true</em:hidden>
targetPlatform (plataforma alvo)
Uma string especificando uma plataforma que o complemento suporte. Isto contém qualquer valor de OS_TARGET sozinho ou combinado com :en:TARGET_XPCOM_ABI, separado por sublinhado (_).
OS_TARGET é típicamente a saída do comando 'uname -s' na plataforma alvo, e.g.:
WINNTpara Windows NT, 2000, XP e mais recentesLinuxpara todas as versões do LinuxDarwinpara todas as versões do MacOS X
Você pode especificar múltiplas propriedades targetPlatform por manifesto. Se algum valor inicia os parâmetros de construção do aplicativo, ele estará instalado; se não, o usuário receberá uma mensagem de erro apropriada.
Exemplos
<em:targetPlatform>WINNT_x86-msvc</em:targetPlatform> <em:targetPlatform>Linux</em:targetPlatform> <em:targetPlatform>Darwin_ppc-gcc3</em:targetPlatform>
Normalmente, você usaria somente a parte do sistema operacional para temas ou para extensões que não são interamente "cross-plataform". Para extensões incluindo componentes binários (compilados), você nunca deve usar o sistema operacional sozinho, mas inclua o :en:ABI (s) que compilou os componentes com. Se você quer incluir múltiplas versões de componentes, você devia usar também :en:Platform-specific Subdirectories.
Notas
- No mesmo arquivo de manifesto, você mesmo pode misturar valores com ou sem ABI. Se um valor para o aplicativo do sistema operacional é encontrado e requisite algum ABI específico, o ABI é considerado importante para este sistema operacional e o aplicativo recusará a instalação do complemento se ele não encontrar uma combinação de partida sistema operacional/ABI. Este meio que todos os exemplos anteriores ocorreram em um manifesto, o complemento instalará em qualquer construção Linux do aplicativo, indiferente de seu ABI, mas não em uma construção Windows Cygwin.
- Talvez possa construir do Firefox e do Thunderbird os quais não "sabem" suas ABI (portas preferidas para plataformas raras, ou construções não-oficiais). Estas construções recusarão a instalação de qualquer complemento que requisite um ABI especifico para sua plataforma.
Firefox 1.5 Esta propriedade foi adicionada para o Firefox/Thunderbird 1.5. Versões anteriores destes aplicativos irão ignorar as restrições e instalaram o complemento sem levar em conta a plataforma.
Referência de propriedade obsoleta
Estas propriedades são requisitadas em versões antigas do Gerenciador de Complementos, mas tem que ser recolocadas com mecanismos novos e melhores.
file (arquivo)
Firefox 1.0 Esta propriedade aponta para um arquivo chrome .jar que contém pacotes chrome que requisitam registro com o Registro Chrome.
A propriedade <em:file> tem um objeto de valor complexo. O URL deste valor é urn:mozilla:extension:file:jarFile.jar onde jarFile.jar é o nome do arquivo jar que contém o pacote de arquivos chrome, un-jarred (e.g. urn:mozilla:extension:file:directory).
Este objeto tem uma propriedade de package (pacote) (com um caminho demtro do arquivo jar ou diretório que leva à localização de onde o arquivo contents.rdf está responsável pelo registro de onde o pacote está localizado), uma propriedade locale (idem, mas para registrar o local) e a propriedade skin (idem, mas para registrar o material do tema).
Em extensões para o Firefox 1.5, esta propriedade não é necessária: o chrome.manifest no nível máximo do XPI é usado para localizar o chrome para registrar. Se não há chrome.manifest, esta propriedade ainda é lida pelo Gerenciador de Complementos e o chrome.manifest é gerado de um antigo estilo contents.rdf.
Exemplos
<em:file> <Description about="urn:mozilla:extension:file:myext.jar"> <em:package>content/myext/</em:package> <em:locale>locale/en-US/myext/</em:locale> <em:skin>skin/classic/myext/<em:skin> </Description> </em:file>
Um Manifesto de Instalação pode especificar múltiplas propriedades file, um por um arquivo jar ou subdiretório que contenha o chrome para registrar.
Glossário
Área de acesso restrito
Uma área de acesso restrito é um local de instalação que pode ser restrito com uma conta de acesso restrito, sem ter em conta se a situação é restringida com privilégios do usuário atual (veja nsIInstallLocation::restricted). Normalmente, a pasta ($APPDIR)/extensions e a localização do registro de instalação embaixo de HKEY_LOCAL_MACHINE (veja en:Adding Extensions using the Windows Registry para detalhes) são restritas.
Os ($PROFILE)/extensions e HKEY_CURRENT_USER locais de instalação, na outra mão, não são restritos.