Venha juntar-se a nós no #hackpack-chrome-ext em Slack para obter ajuda, sair e mostrar o seu projeto!

>

Visão Geral

Congratulações! Você escolheu este hackpack, e está no caminho certo para construir um produto super legal!

Neste hackpack, você vai construir uma extensão cromada que substitui o conteúdo em páginas web de acordo com regras personalizáveis. Num relance, as suas tarefas incluirão:

1. Substituir todas as instâncias do texto “cal” em todas as páginas web.
2. Substituir todo o texto de uma página web de acordo com as regras de substituição especificadas pelo utilizador.
3. Substituir todas as imagens em um site de acordo com as regras de substituição especificadas pelo usuário.

Depois de terminar estas tarefas, você terá construído um aplicativo excitante que você pode usar no seu próprio navegador!

Começando

1. Baixe e descompacte o código inicial.

Você deve ter aproximadamente os seguintes arquivos.

hackpack-chrome-ext-master/├── README.md├── manifest.json├── icons│ ├── TreeHacks-white-128.png│ ├── TreeHacks-white-16.png│ ├── TreeHacks-white-19.png│ ├── TreeHacks-white-32.png│ ├── TreeHacks-white-48.png│ ├── TreeHacks-white-64.png│ └── TreeHacks-white-96.png└── src ├── bg │ └── background.js ├── browser_action │ ├── browser_action.css │ ├── browser_action.html │ └── browser_action.js ├── inject │ └── inject.js └── options ├── options.css ├── options.html └── options.js

Alternativamente, se você é um mestre Git, você pode sincronizar com nosso repositório Git sobre HTTPS ou SSH. Nota: Se você não está familiarizado com Git, ou não sabe o que as seguintes linhas fariam, não execute os seguintes comandos!

>

# From Terminal.app or equivalent...# Clone via HTTPS$ git clone https://github.com/TreeHacks/hackpack-chrome-ext.git# or SSH$ git clone [email protected]:TreeHacks/hackpack-chrome-ext.git

Comece a usar

Baixe o Google Chrome

Para construir uma extensão do Chrome, você precisará do Google Chrome! Se você ainda não baixou o Chrome, baixe a versão mais recente aqui. Para este hackpack, você vai precisar do Chrome Versão 40 ou mais recente. Para descobrir qual versão você tem, vá para chrome://version/ no Omnibar, e veja a linha superior. Você deve ver algo como

Google Chrome48.0.2564.109 (Official Build) (64-bit)

Não se preocupe se não for exatamente o mesmo. Desde que o número maior (antes do ponto decimal) seja maior que 40, você está configurado!

Carregar o Código de Inicialização

Chrome geralmente envia extensões como .crx arquivos (semelhante a .zip arquivos), o que é ótimo para distribuição, mas não tão bom para desenvolvimento. Em vez disso, vamos dizer ao Chrome para tratar a pasta de código inicial como uma extensão.

Precisamos habilitar as Configurações do Desenvolvedor Chrome para construir nossa extensão chrome.

Para fazer isso:

1. Navigate para chrome://extensões no seu navegador.
2. Certifique-se de que a caixa de verificação do modo Developer no canto superior direito está marcada.
3. Click Load unpacked extension… para abrir uma caixa de diálogo de selecção de ficheiros.
4. Navegue até o diretório em que seus arquivos de extensão vivem, e selecione-o.

Você deve agora ver uma tela que se parece com a seguinte:

Note que a caixa de verificação do modo Desenvolvedor está marcada, e a extensão está ativada.

Adicionalmente, preste muita atenção no link Reload.

Por padrão, o Chrome não irá recarregar sua extensão automaticamente se você atualizar seu código. Assim, se você quiser testar sua extensão, você deve recarregar a extensão antes de testar. Caso contrário, as suas alterações não estarão presentes na extensão activa. Basicamente, sempre que fizer uma alteração ao seu código que deseja testar ao vivo no Chrome, certifique-se de recarregar a extensão usando aquele botão Reload.

Background Knowledge

Para este projeto, você precisará de algum conhecimento de Javascript e Extensões Chrome. O código inicial deve ter comentários suficientes para explicar cada arquivo, mas se você quiser ter um entendimento mais profundo desses sistemas antes de começar o hackpack, fornecemos links para alguns tutoriais abaixo. Em particular, se nunca viu Javascript antes, recomendamos vivamente um tutorial de Javascript.

Saiba mais sobre Javascript

O que é JavaScript?

JavaScript é uma linguagem de script para computadores. É muitas vezes executado em aplicações de web browser para criar conteúdo dinâmico como uma mensagem popup ou um relógio ao vivo. Não está relacionada com a linguagem de programação Java.

Aqui estão alguns dos nossos tutoriais favoritos de Javascript!

Se você é um especialista em várias linguagens de programação antes, ou se você já conhecia Javascript e só precisa de uma atualização na sintaxe, confira Learn X in Y Minutes. Este tutorial leva cerca de 10 minutos.

Se você nunca viu (ou ouviu falar) Javascript antes, ou se você quer um tutorial detalhado e envolvido que o leve através do Javascript a partir do zero, recomendamos a Codecademy. Este tutorial leva cerca de 10 horas.

Se você quer um tutorial abrangente de todas as coisas Javascript, confira W3 Escolas. Este tutorial leva cerca de 10 horas.

O curso, você está livre para encontrar seus próprios tutoriais, ou aprender fazendo.

O básico das Extensões Chrome

O que são Extensões Chrome?

Extensões são pequenos programas de software que podem modificar e melhorar a funcionalidade do navegador Chrome. Escreve-os utilizando tecnologias Web como HTML, JavaScript e CSS.

Se quiser saber mais sobre as Extensões Chrome, leia a introdução da Google às extensões e a visão geral de alto nível da Google.

Ponto de verificação 1: Cal to Butt

Com tudo isso fora do caminho, vamos começar!

Task A: Leia o código inicial

Antes de começar a escrever qualquer código, leia o código inicial e os comentários que fornecemos. Em particular, leia tudo de src/inject/inject.js, porque você estará fazendo a maioria das suas alterações nesse arquivo. Se você tiver alguma dúvida, esta seria uma grande oportunidade de pedir ajuda no nosso canal Slack!

Task B: Update modifyText para substituir cada instância de ‘cal’ por ‘butt’

Para a primeira tarefa, você irá atualizar a função modifyText em src/inject/inject.js para substituir cada instância de ‘cal’ do substrato pela string ‘butt’ em uma palavra dada e retornar a string modificada. Para a Parte 1, a variável settings será nula.

Por exemplo, modifyText('calhacks organizer', null) deverá retornar butthacks organizer.

/* File src/inject/inject.js */function modifyText(text, settings) {// YOUR CODE HEREreturn text;}

Teste seu método visitando a página Wiki da UC Berkeley ou o site CalHacks. Eu pessoalmente gosto da página Wiki Calculus.

(Dica: Confira a documentação em JavaScript String replace)

Edge cases: O que acontece com a string 'iCalendar'? Tente atualizar modifyText para que ela respeite o caso original do substrato cal. Ou seja, 'cal' -> 'butt', mas também 'Cal' -> 'Butt' e 'CAL' -> 'BUTT'. Que outros esquemas de caixa comuns a sua função terá em conta?

Ponto de verificação 2: Traduções personalizadas

Não somos os primeiros a pensar nisto. Se você ler o XKCD, algumas destas coisas podem parecer-lhe familiares. Se você não leu XKCD, bem, é hora de fazer uma pausa na codificação e ler algumas boas e antigas webcomics à moda antiga. Aqui estão alguns dos nossos favoritos.

Estes quadrinhos mostram algumas grandes substituições de texto, que são reproduzidas aqui em formato de texto em quadrinhos.

batman -> a man dressed like a batkeyboard -> leopardwitnesses -> these dudes i knowallegedly -> kinda probablynew study -> tumblr postrebuild -> avengespace -> spaaacegoogle glass -> virtual boysmartphone -> pokedexelectric -> atomicsenator -> elf-lordcar -> catelection -> eating contestcongressional leaders -> river spiritshomeland security -> homestar runnercould not be reached for comment -> is guilty and everyone knows itforce -> horsedebate -> dance-offself driving -> uncontrollably swervingpoll -> psychic readingcandidate -> airbenderdrone -> dogvows to -> probably won'tat large -> very largesuccessfully -> suddenlyexpands -> physically expandsfirst-degree -> friggin' awfulsecond-degree -> friggin' awfulthird-degree -> friggin' awfulan unknown number -> like hundredsfront runner -> blade runnerglobal -> sphericalyears -> minutesminutes -> yearsno indication -> lots of signsurgedrestraint by -> drunkenly egged onhorsepower -> tons of horsemeat

E, claro, as nossas próprias

cal -> butt

Vamos usar esta “sintaxe de seta” para representar uma regra de substituição de texto para o resto deste projecto. Em particular, vamos deixar

pattern -> replacement

representar a transformação da string "pattern" para a string "replacement". Por exemplo, "years -> minutes" significa que substituímos cada instância da substring "years" pela string "minutes", e "minutes -> years" significa que substituímos cada instância da substring "minutes" pela string "years".

Task C: Parse uma lista de strings em um mapa de regras de substituição.

Para esta tarefa, você irá escrever a função parseSettings em src/inject/inject.js para converter um array de entrada de linhas representando regras de substituição e sair um mapa de padrões para suas substituições.

A assinatura da função é

function parseSettings(lines) { // YOUR CODE HEREreturn null;}

Por exemplo,

parseSettings()

Deve retornar

{ "batman": "a man dressed like a bat", "keyboard": "leopard", "force": "horse"}

É garantido que cada entrada no array de linhas contém o substring '->' pelo menos uma vez.

Caixas de edição: Como a sua função processa a linha "a -> b -> c". Ela a transforma em "a": "b -> c", em "a -> b": "c", ou algo mais? E se não houver padrão (ou seja, a linha se parece com "->word" sem texto antes da seta)? E se não houver substituição (ou seja, a linha se parece com "word->" sem texto após a seta)? E a linha com apenas 2 caracteres -> (isto é, sem texto antes ou depois da seta)? Como a sua função lida com os espaços em branco? Ela processa a linha " a -> b " como "a":"b" ou como " a ": " b "? O que acontece se houver duas linhas diferentes, cada uma com o mesmo padrão. Por exemplo, talvez uma linha do array seja "force->horse" e outra entrada seja "force->fore"?

Task D: Use um mapa de regras de substituição para executar várias substituições de texto

Encerramento completado a função parseSettings, agora precisamos voltar à função modifyText para usar nossas novas regras de substituição! O código inicial pegará o valor de retorno da sua função parseSettings e o passará para a função modifyText como a settings variável.

Para esta tarefa, você precisará atualizar modifyText em src/inject/inject.js, para que todas as regras de substituição do mapa sejam promulgadas.

Por exemplo, se o mapa contém uma associação entre "force" e "horse" (ou seja settings = "horse"), então qualquer instância da substring "force" deve ser substituída pela string "horse" no texto, e assim por diante para o resto dos pares pattern: replacement no mapa. Como sempre, você ainda deve substituir "cal" por "butt"

Edge cases: Em que ordem as substituições são avaliadas? Suponha que settings = {'train':'bus', 'use':'eat'}. O que acontece com a string "trainer"? Será que train se aplica primeiro, levando a buser e depois a beatr? Ou use aplica-se primeiro (sem efeito), seguido de train para uma string final de buser? Como no ponto de verificação 1, como você lida com o caso do texto original? Existe uma forma geral de respeitar o caso original?

Usando a acção do browser.

Para testar esta função, fornecemos-lhe uma acção do browser para a extensão. No canto superior direito da janela Chrome, haverá um pequeno ícone TreeHacks).

Clique no ícone para revelar uma IU onde você pode inserir regras de substituição. As regras de substituição que você inserir serão passadas para as suas funções e aplicadas à página. Uma imagem disto é mostrada abaixo:

O texto que você digitar nesta caixa é persistente – não desaparecerá quando você fechar o popup. Se você estiver interessado, o código para fazer isso está em src/browser_action/. Ao pressionar o botão Save, o texto é salvo no armazenamento local do Chrome, e ao pressionar o botão Clear, o armazenamento local é limpo.

>

Checkpoint 3: Image Replacement

Para o 3º e último checkpoint, você vai estender a funcionalidade da extensão para permitir que o usuário especifique as substituições de imagem, assim como as substituições de texto.

Desde que esta é a parte final do hackpack, estamos dando um pouco menos de orientação e um pouco mais de liberdade aqui. Você pode usar qualquer esquema de codificação que quiser para representar as regras de tradução de imagens. Sugerimos que você use o esquema img->https://path.to/image.png para indicar que todas as imagens devem ser substituídas pela imagem em https://path.to/image.png. Dependendo de como você escolher representar suas regras de substituição de imagens, você pode ter passos separados daqueles abaixo.

Task E: Encontre todas as imagens em uma determinada página web.

Se quisermos substituir todas as imagens em uma página web, precisaremos primeiro ter todas as imagens nessa página web. Escreva um método (helper) que retorna uma lista de todas as imagens de uma página.

Você pode ser tentado a usar jQuery, mas fique avisado – incorporar jQuery em uma extensão Chrome não é fácil, e há uma maneira de resolver isso usando vanilla JS. Se você precisar de uma dica, verifique a documentação para querySelectorAll.

Task F: Update parseSettings para lidar com regras de substituição de imagens, além de regras de substituição de texto.

Você precisará alterar a implementação de parseSettings para ficar atento à(s) regra(s) de substituição de imagens. Como você irá representar uma regra de substituição de imagem?

Task G: Atualize a fonte de cada imagem na página.

Após ter as imagens e a URL de substituição, escreva o código para atualizar a imagem original de modo que ela exiba a URL de destino. Se você precisar de uma dica, veja o atributo src nas imagens.

Task H: We’re All in This Together

Com estes métodos de ajuda em mãos, implemente a função replaceAllImages em src/inject/inject.js. Esta função é chamada imediatamente após as substituições de texto serem avaliadas. Se tudo correr bem, você deve ser capaz de inserir uma regra de substituição de imagem na ação do navegador, e ver que todas as imagens são substituídas!

Parabéns!

Você conseguiu! Muito bem feito! Você construiu uma extensão cromada legal que substitui conteúdo em websites, e além disso, você pode mantê-la!

Tire um momento para relaxar, respirar fundo, e olhar para trás no projeto que você construiu. É muito impressionante!

Se você chegar a este ponto, venha ao canal Slackpack-chrome-ext para comemorar! Você merece.

Extensões

A um alto nível, você construiu um sistema que se baseia na passagem de mensagens entre um diálogo popup (ação do navegador do Chrome) e um script que roda em todas as páginas da web. Temos usado isso para passar informações sobre substituições de texto e imagem para o script de injeção, mas não há razão para pararmos por aí!

Você pode estender esse framework para construir projetos realmente legais. O céu é o limite, mas nós demos algumas sugestões aqui.

• Match more than just just text – match regular expressions! Estenda a funcionalidade de modifyText para tratar os padrões de settings como representando expressões regulares, não apenas texto simples.
• Correspondência de suporte em seletores de documentos do DOM. Correspondência em nomes de tags (como img, mas também a e iframe), ou .class nomes, ou talvez até mesmo #ids. Você pode construir suporte para o conjunto completo de seletores?
• Não substitua todas as imagens – apenas substitua algumas (digamos 1%). Pode alterar os links do youtube (a tags com um href contendo "youtube") para vídeos do Rick Astley?

Movendo-se do reino dos substitutos,

• Permitir que o usuário sinalize informações para o script de fundo. Talvez pedir-lhes o seu nome, e destacar a vermelho qualquer texto que contenha o seu nome.
• Deixe o utilizador especificar um monte de servidores para agir como proxies. Você construiu um Tor!
• Permitir que um usuário insira seus dados de saúde, e sugerir (via popup ou redirecionamento amigável) que ele exercite cada período de tempo que passa navegando em um site (tosse avermelhada).

Isto é apenas o começo. Deixe sua imaginação correr solta. Nós não podemos esperar para ver o que você constrói!

Miscelânea

Feedback

Se você tiver qualquer comentário, positivo ou negativo, alcance Sam Redmond (@organizer-sam on Slack) com feedback! Nós gostaríamos de ouvir o que você acha que é ótimo, e o que você acha que nós podemos melhorar.

Crédito

Crédito para a idéia vai para os originadores da Extensão de Cromo Nublado, crédito para grande documentação (grande parte da qual nós roubamos sem vergonha) vai para os contribuidores de Cromo, e crédito para as imagens vai para XKCD.

Licença

MIT