Passo-a-Passo
Neste artigo iremos criar uma Extensão para Firefox do início ao fim.
A extensão adicionará um novo botão na barra de ferramentas do Firefox. Quando clicar no botão se exibirá um popup habilitando a escolha de um animal. Uma vez que o usuário escolher um animal, a página atual do navegador será substituida por uma imagem do animal escolhido.
Para implementar esse extensão, será necessário:
-
definir a ação do navegador, que é um botão ligado a barra de ferramentas. Para o botão nós iremos fornecer:
- um icone chamado "beasts.png"
- um popup para abrir quando o botão for pressionado. O popup irá ter incluso HTML, CSS e JavaScript.
-
escrever um content script, "beastify.js" que irá ser injetado na página web. Este é o código que irá modificar a página.
-
empacotar alguma imagens de animais para substituir na página. Nós iremos criar as imagens "web accessible resources" então a página poderá referenciar eles.
Você pode visualizar toda a estrutura da extensão da seguinte forma:
É uma extensão extremamente simples, mas mostra muitos conceitos básicos da API de Extensões:
- adicionando um botão na barra de ferramentas
- Definindo um panel de popup usando HTML, CSS e JavaScript
- Injetando content scripts nas páginas
- comunicação entre content scripts e o resto das extensões
- empacotando recursos com sua extensão que serão usadas nas páginas
Você pode encontrar o código completo da extensão no GitHub.
Para criar essa extensão você precisará do Firefox 45 ou mais recente.
Escrevendo a WebExtension
Crie um novo diretório e navegue até ele:
mkdir beastify
cd beastify
manifest.json
Agora crie um novo arquivo chamado "manifest.json", e insira o seguinte conteúdo:
{
"manifest_version": 2,
"name": "Beastify",
"version": "1.0",
"applications": {
"gecko": {
"id": "beastify@mozilla.org"
}
},
"permissions": ["http://*/*", "https://*/*"],
"browser_action": {
"default_icon": "button/beasts.png",
"default_title": "Beastify",
"default_popup": "popup/choose_beast.html"
},
"web_accessible_resources": [
"beasts/frog.jpg",
"beasts/turtle.jpg",
"beasts/snake.jpg"
]
}
-
As primeiras três chaves :
manifest_version
,name
, eversion
, são obrigatórias e contém metadados básicos para a extensão. -
permissions
lista as permisões que a extensão precisa. Nós iremos apenas perguntar se pediremos permissão para modificar todas as páginas HTTP e HTTPS : veja a documentação para as chaves depermissions
. Nós prefirimos por usar a permissãoactiveTab
aqui , mas atualmente não é suportada pela Firefox. -
browser_action
especifica o botão da barra de ferramentas. Iremos fornecer três informações aqui:default_icon
é obrigatório, e aponta para o icone do botãodefault_title
é opicional, e mostra a mensagem em um tooltipdefault_popup
é usado se você quer que um popup seja mostrado quando o usuário clicar no botão. Nós fazemos isto, então incluímos esta chave e apontamos para um arquivo HTML incluído na extensão.
-
web_accessible_resources
lista arquivos que queremos criar tornar acessível para as páginas. Uma vez que a extensão substitui as imagens da página com imagens que já empacotamos com a extensão , nós precisamos fazer estas imagens acessíveis à página.
Perceba que todos os caminhos são relativos ao manifest.json.
O Botão na barra de ferramentas
O botão na barra de ferramentas precisa de um icone, e nosso manifest.json informa que nós teriamos um icone em "button/beasts.png".
Crie o diretório "button" e copie o icone com o nome "beasts.png". Você poderá usar um dos nossos exemplo, que é retirado do Aha-Soft's Free Retina iconset e usado sob os termos de sua licença.
Se você não fornecer um popup, então um evento de click é lançado para sua extensão quando o usuário clicar no botão. Se você fornecer um popup, o evento de click não envia, mas ao invés disso, o popup é aberto. Nós queremos abrir um popup, então vamos criá-lo na próxima etapa.
O popup
A função do popup é ativar a escolha do usuário para um dos três animais.
Crie um novo diretório chamado "popup" na raiz do projeto. Aqui é onde nós criar os códigos para o popup. O popup irá ser constituido em três arquivos :
choose_beast.html
Define o conteúdo do panelchoose_beast.css
Estilo do conteúdochoose_beast.js
Captura a escolha do usuário executando um content script a aba ativa
choose_beast.html
O arquivo HTML criado é este:
<!doctype html>
<html>
<head>
<meta charset="utf-8" />
<link rel="stylesheet" href="choose_beast.css" />
</head>
<body>
<div class="beast">Frog</div>
<div class="beast">Turtle</div>
<div class="beast">Snake</div>
<script src="choose_beast.js"></script>
</body>
</html>
Nós temos um elemento para cada escolha de animal. Perceba que nós incluimos os arquivo CSS e JS nesse arquivo, igual a uma página web.
choose_beast.css
O CSS ajusta o tamanho do popup, garantindo que as três escolhas irão preencher o espaço, e daremos a eles algum estilo básico:
html,
body {
height: 100px;
width: 100px;
margin: 0;
}
.beast {
height: 30%;
width: 90%;
margin: 3% auto;
padding-top: 6%;
text-align: center;
font-size: 1.5em;
background-color: #e5f2f2;
cursor: pointer;
}
.beast:hover {
background-color: #cff2f2;
}
choose_beast.js
No JavaScript para o popup, nós iremos "escutar" o evento de click . Se o clique foi em uma das três escolhas de animais, nós iremos injetar um content script na aba ativa. Um vez que o content script é carregado , nós enviaremos uma mensagem com o animal escolhido:
document.addEventListener("click", function (e) {
if (!e.target.classList.contains("beast")) {
return;
}
var chosenBeast = e.target.textContent;
chrome.tabs.executeScript(null, {
file: "/content_scripts/beastify.js",
});
chrome.tabs.query({ active: true, currentWindow: true }, function (tabs) {
chrome.tabs.sendMessage(tabs[0].id, { beast: chosenBeast });
});
});
É usado três funções da API WebExtension:
chrome.tabs.executeScript
Para injetar um content script que se encontra em "content_scripts/beastify.js" na aba ativachrome.tabs.query
Obter a aba ativachrome.tabs.sendMessage
para enviar uma mensagem para o content scripts executando na aba ativa. A mensagem irá conter as propriedades do animal escolhido.
O content script
Crie a novo diretório na pasta root do projeto chamado "content_scripts" e crie um novo arquivo com o nome "beastify.js", com o seguinte conteúdo:
// Assign beastify() as a listener for messages from the extension.
chrome.runtime.onMessage.addListener(beastify);
function beastify(request, sender, sendResponse) {
removeEverything();
insertBeast(beastNameToURL(request.beast));
chrome.runtime.onMessage.removeListener(beastify);
}
function removeEverything() {
while (document.body.firstChild) {
document.body.firstChild.remove();
}
}
function insertBeast(beastURL) {
var beastImage = document.createElement("img");
beastImage.setAttribute("src", beastURL);
beastImage.setAttribute("style", "width: 100vw");
beastImage.setAttribute("style", "height: 100vh");
document.body.appendChild(beastImage);
}
function beastNameToURL(beastName) {
switch (beastName) {
case "Frog":
return chrome.extension.getURL("beasts/frog.jpg");
case "Snake":
return chrome.extension.getURL("beasts/snake.jpg");
case "Turtle":
return chrome.extension.getURL("beasts/turtle.jpg");
}
}
O content script adiciona um listener da mensagem para a extensão (especificamente , para "choose_beast.js"). No listener:
- remover todos os elementos em
document.body
- transforma os nomes dos animais em uma URL para ser usada na imagem
- Cria uma tag
<img>
, e insere no DOM - Remove a mensagem da listener
Os animais
Finalmente, nós precisamos incluir as imagens dos animais.
Crie um novo diretório chamado "beasts", e adicione as três imagens nos diretório, com os nomes apropriados. Você pode obter as imagens aqui no GitHub, ou aqui:
Empacotando e instalando
Verifique se os seus arquivos estão estruturados de acordo com as informações abaixo:
beastify/ beasts/ frog.jpg snake.jpg turtle.jpg button/ beasts.png content_scripts/ beastify.js popup/ choose_beast.css choose_beast.html choose_beast.js manifest.json
Extensões Firefox são empacotados como arquivos XPI, que são apenas arquivos ZIP com a extensão "XPI".
Um truque é que o arquivo ZIP deve ser um dos arquivos de extensão . Portanto, para criar um XPI a partir dos arquivos beastify , navegue até o diretório " beastify " em um shell de comando e digite:
# in beastify/
zip -r ../beastify.xpi *
Ou você pode compactar com alguma ferramenta do tipo WinRar escolhe a forma de empacotação ZIP e subistituir .zip para XPI
Para instalar o XPI, você apenas irá abrir o Firefox:
- Vá até o Arquivos, seleciona Abrir arquivo, ou pressione Ctrl/Cmd+O
- selecione "beastify.xpi" na caixa de dialógo que abriu
Você deverá receber um aviso de que você está instalando uma extensão não assinada. Aceite o aviso de advertência.
Você poderá ver o icone aparecer na barra de ferramentas. Abra uma nova página web, então click no icone, selecione um animal e veja a imagem que você escolheu na página.