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:

![](/pt-BR/docs/Mozilla/Add-ons/WebExtensions/Your_second_WebExtension/beastify-anatomy.svg)

É 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:


```bash
mkdir beastify
cd beastify
```

### manifest.json

Agora crie um novo arquivo chamado "manifest.json", e insira o seguinte conteúdo:


```json
{
  "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`**, e **`version`**, 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 de `permissions`. Nós prefirimos por usar a permissão `activeTab` 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ão
    + **`default_title`** é opicional, e mostra a mensagem em um tooltip
    + **`default_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 panel
* **`choose_beast.css`** Estilo do conteúdo
* **`choose_beast.js`** Captura a escolha do usuário executando um content script a aba ativa

#### choose\_beast.html

O arquivo HTML criado é este:


```html
<!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:


```css
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:


```js
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 ativa
* **`chrome.tabs.query`** Obter a aba ativa
* **`chrome.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:


```js
// 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:

![](/pt-BR/docs/Mozilla/Add-ons/WebExtensions/Your_second_WebExtension/frog.jpg)
![](/pt-BR/docs/Mozilla/Add-ons/WebExtensions/Your_second_WebExtension/snake.jpg)
![](/pt-BR/docs/Mozilla/Add-ons/WebExtensions/Your_second_WebExtension/turtle.jpg)

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:


```bash
   # 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.