Venez nous rejoindre sur #hackpack-chrome-ext sur Slack pour obtenir de l’aide, traîner et montrer votre projet !

Aperçu

Congratulations ! Vous avez choisi ce hackpack, et vous êtes bien parti pour construire un produit super cool !

Dans ce hackpack, vous allez construire une extension chrome qui remplace le contenu des pages web selon des règles personnalisables. En un coup d’œil, vos tâches comprendront :

1. Remplacer toutes les instances du texte « cal » sur toutes les pages web.
2. Remplacer tout le texte sur une page web selon des règles de remplacement spécifiées par l’utilisateur.
3. Remplacer toutes les images sur une page web selon les règles de remplacement spécifiées par l’utilisateur.

Après avoir terminé ces tâches, vous aurez construit une application passionnante que vous pourrez utiliser dans votre propre navigateur !

Démarrage

1. Téléchargez et décompressez le code de démarrage.

Vous devriez à peu près avoir les fichiers suivants.

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

Alternativement, si vous êtes un maître Git, vous pouvez vous synchroniser avec notre dépôt Git via HTTPS ou SSH. Remarque : si vous n’êtes pas familier avec Git, ou si vous ne savez pas ce que feraient les lignes suivantes, n’exécutez pas les commandes suivantes !

# 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

Démarrage

Télécharger Google Chrome

Pour construire une extension Chrome, vous aurez besoin de Google Chrome ! Si vous n’avez pas encore téléchargé Chrome, téléchargez la dernière version ici. Pour ce hackpack, vous aurez besoin de la version 40 de Chrome ou d’une version plus récente. Pour savoir quelle version vous avez, allez à chrome://version/ dans l’Omnibar, et regardez la ligne supérieure. Vous devriez voir quelque chose comme

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

Ne vous inquiétez pas si ce n’est pas exactement la même chose. Tant que le nombre majeur (avant la virgule) est supérieur à 40, vous êtes prêt!

Chrome expédie généralement les extensions sous forme de fichiers .crx (similaires aux fichiers .zip), ce qui est génial pour la distribution, mais pas si génial pour le développement. Au lieu de cela, nous allons dire à Chrome de traiter le dossier du code de démarrage comme une extension.

Nous devons activer les paramètres du développeur Chrome afin de construire notre extension chrome.

Pour ce faire :

1. Naviguez vers chrome://extensions dans votre navigateur.
2. Assurez-vous que la case du mode développeur dans le coin supérieur droit est cochée.
3. Cliquez sur Load unpacked extension… pour faire apparaître une boîte de dialogue de sélection de fichier.
4. Naviguez jusqu’au répertoire dans lequel se trouvent vos fichiers d’extension, et sélectionnez-le.

Vous devriez maintenant voir un écran qui ressemble à celui ci-dessous:

Notez que la case du mode développeur est cochée, et que l’extension est activée.

En outre, prêtez une attention particulière au lien Reload.

Par défaut, Chrome ne rechargera pas votre extension automatiquement si vous mettez à jour votre code. Ainsi, si vous voulez tester votre extension, vous devez recharger l’extension avant de la tester. Sinon, vos modifications ne seront pas présentes dans l’extension active. Fondamentalement, chaque fois que vous apportez une modification à votre code que vous voulez tester en direct dans Chrome, assurez-vous de recharger l’extension en utilisant ce bouton Reload.

Connaissances de base

Pour ce projet, vous aurez besoin de quelques connaissances de Javascript et des extensions Chrome. Le code de démarrage devrait avoir suffisamment de commentaires pour expliquer chaque fichier, mais si vous voulez avoir une compréhension plus approfondie de ces systèmes avant de commencer le hackpack, nous avons fourni des liens vers quelques tutoriels ci-dessous. En particulier, si vous n’avez jamais vu Javascript auparavant, nous vous recommandons fortement de passer par un tutoriel Javascript.

Apprendre à connaître Javascript

Qu’est-ce que JavaScript ?

JavaScript est un langage de script pour les ordinateurs. Il est souvent exécuté dans les applications de navigateur web pour créer du contenu dynamique comme un message popup ou une horloge en direct. Il n’est pas lié au langage de programmation Java.

Voici quelques-uns de nos tutoriels Javascript préférés !

Si vous êtes un expert dans plusieurs langages de programmation avant, ou si vous aviez l’habitude de connaître Javascript et que vous avez juste besoin d’un rafraîchissement de la syntaxe, consultez Apprendre X en Y minutes. Ce tutoriel prend environ 10 minutes.

Si vous n’avez jamais vu (ou entendu parler) de Javascript auparavant, ou si vous voulez un tutoriel approfondi et impliqué qui vous fait passer par Javascript à partir de la base, nous recommandons Codecademy. Ce tutoriel prend environ 10 heures.

Si vous voulez un tutoriel complet de tout ce qui concerne Javascript, consultez W3 Schools. Ce tutoriel prend environ 10 heures.

Bien sûr, vous êtes libre de trouver vos propres tutoriels, ou d’apprendre en faisant.

Les bases des extensions Chrome

Que sont les extensions Chrome ?

Les extensions sont de petits logiciels qui peuvent modifier et améliorer les fonctionnalités du navigateur Chrome. Vous les écrivez à l’aide de technologies Web telles que HTML, JavaScript et CSS.

Si vous voulez en savoir plus sur les extensions Chrome, lisez l’introduction aux extensions et la présentation de haut niveau de Google.

Point de contrôle 1 : Cal à Butt

Avec tout cela de réglé, commençons !

Tâche A : lire le code de démarrage

Avant de commencer à écrire du code, lisez le code de démarrage et les commentaires que nous avons fournis. En particulier, lisez tout le src/inject/inject.js, parce que vous ferez la plupart de vos changements dans ce fichier. Si vous avez des questions, ce serait une excellente occasion de demander de l’aide sur notre canal Slack !

Tâche B : Mettre à jour modifyText pour remplacer chaque instance de ‘cal’ par ‘butt’

Pour la première tâche, vous mettrez à jour la fonction modifyText dans src/inject/inject.js pour remplacer chaque instance de la sous-chaîne ‘cal’ par la chaîne ‘butt’ dans un mot donné et renvoie la chaîne modifiée. Pour la première partie, la variable settings sera nulle.

Par exemple, modifyText('calhacks organizer', null) devrait retourner butthacks organizer.

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

Testez votre méthode en visitant la page Wiki de l’UC Berkeley ou le site CalHacks. Personnellement, j’aime bien la page Wiki de Calculus.

(Indice : consultez la documentation sur le remplacement des chaînes de caractères en JavaScript)

Cas limites : Qu’arrive-t-il à la chaîne 'iCalendar' ? Essayez de mettre à jour modifyText pour qu’elle respecte le cas original de la sous-chaîne cal. C’est-à-dire 'cal' -> 'butt', mais aussi 'Cal' -> 'Butt' et 'CAL' -> 'BUTT'. Quels autres schémas de casse courants votre fonction prendra-t-elle en compte ?

Point de contrôle 2 : Traductions personnalisées

Nous ne sommes pas les premiers à y penser. Si vous lisez XKCD, certains de ces éléments peuvent vous sembler familiers. Si vous n’avez pas lu XKCD, eh bien, il est temps de faire une pause de codage et de lire quelques bons vieux webcomics. Voici quelques-unes de nos préférées.

Ces bandes dessinées présentent de superbes remplacements de texte, qui sont reproduits ici en clair.

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

Et bien sûr, notre très propre

cal -> butt

Nous allons utiliser cette « syntaxe fléchée » pour représenter une règle de remplacement de texte pour le reste de ce projet. En particulier, nous allons laisser

pattern -> replacement

représenter la transformation de la chaîne "pattern" en chaîne "replacement". Par exemple, "years -> minutes" signifie que nous remplaçons chaque instance de la sous-chaîne "years" par la chaîne "minutes", et "minutes -> years" signifie que nous remplaçons chaque instance de la sous-chaîne "minutes" par la chaîne "years".

Tâche C : Parse une liste de chaînes de caractères en une carte de règles de remplacement.

Pour cette tâche, vous écrirez la fonction parseSettings dans src/inject/inject.js pour convertir un tableau d’entrée de lignes représentant des règles de remplacement et sortir une carte des motifs vers leurs remplacements.

La signature de la fonction est

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

Par exemple,

parseSettings()

doit retourner

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

Vous avez la garantie que chaque entrée du tableau de lignes contient la sous-chaîne '->' au moins une fois.

Cas limites : Comment votre fonction traite-t-elle la ligne "a -> b -> c". La transforme-t-elle en "a": "b -> c", en "a -> b": "c", ou en autre chose ? Que se passe-t-il s’il n’y a pas de modèle (c’est-à-dire que la ligne ressemble à "->word" sans texte avant la flèche) ? Et s’il n’y a pas de remplacement (c’est-à-dire que la ligne ressemble à "word->" sans texte après la flèche) ? Qu’en est-il de la ligne avec seulement 2 caractères -> (c’est-à-dire aucun texte avant ou après la flèche) ? Comment votre fonction gère-t-elle les espaces blancs ? Traite-t-elle la ligne " a -> b " comme "a":"b" ou comme " a ": " b " ? Que se passe-t-il s’il y a deux lignes différentes, chacune avec le même motif. Par exemple, peut-être qu’une ligne du tableau est "force->horse" et qu’une autre entrée est "force->fore"?

Tâche D : Utiliser une carte de règles de remplacement pour effectuer plusieurs remplacements de texte

Ayant terminé la fonction parseSettings, nous devons maintenant retourner à la fonction modifyText pour utiliser nos nouvelles règles de remplacement ! Le code de démarrage prendra la valeur de retour de votre fonction parseSettings et la passera dans la fonction modifyText en tant que variable settings.

Pour cette tâche, vous devrez mettre à jour modifyText en src/inject/inject.js, afin que toutes les règles de remplacement de la carte soient promulguées.

Par exemple, si la carte contient une association entre "force" et "horse" (c’est-à-dire settings = "horse"), alors toute instance de la sous-chaîne "force" doit être remplacée par la chaîne "horse" dans le texte, et ainsi de suite pour le reste des paires pattern: replacement de la carte. Comme toujours, vous devriez toujours remplacer "cal" par "butt"

Cas de bord : Dans quel ordre les remplacements sont-ils évalués ? Supposons settings = {'train':'bus', 'use':'eat'}. Que se passe-t-il avec la chaîne "trainer" ? Est-ce que train s’applique en premier, conduisant à buser puis beatr ? Ou est-ce que use s’applique d’abord (sans effet), suivi de train pour une chaîne finale de buser ? Comme dans le point de contrôle 1, comment gérer le cas du texte original ? Y a-t-il un moyen général de respecter la casse d’origine ?

Utilisation de l’action du navigateur.

Afin de tester cette fonction, nous vous avons fourni une action du navigateur pour l’extension. Dans le coin supérieur droit de la fenêtre Chrome, il y aura une petite icône TreeHacks).

Cliquez sur l’icône pour révéler une interface utilisateur où vous pouvez entrer des règles de remplacement. Les règles de remplacement que vous saisissez seront passées dans vos fonctions et appliquées à la page. Une capture d’écran de ceci est montrée ci-dessous:

Le texte que vous entrez dans cette boîte est persistant – il ne disparaîtra pas lorsque vous fermez la popup. Si vous êtes intéressé, le code pour faire cela est dans src/browser_action/. En appuyant sur le bouton d’enregistrement, vous enregistrez le texte dans le stockage local de Chrome, et en appuyant sur le bouton d’effacement, vous effacez le stockage local.

Checkpoint 3 : Remplacement d’image

Pour le 3e et dernier checkpoint, vous allez étendre la fonctionnalité de l’extension pour permettre à l’utilisateur de spécifier des remplacements d’image, tout comme les remplacements de texte.

Comme il s’agit de la dernière partie du hackpack, nous vous donnons un peu moins de conseils et un peu plus de liberté ici. Vous pouvez utiliser le schéma d’encodage que vous voulez pour représenter les règles de traduction d’images. Nous vous suggérons d’utiliser le schéma img->https://path.to/image.png pour indiquer que toutes les images doivent être remplacées par l’image à https://path.to/image.png. Selon la façon dont vous choisissez de représenter vos règles de remplacement d’images, vous pouvez avoir des étapes distinctes de celles ci-dessous.

Tâche E : Trouver toutes les images sur une page web donnée.

Si nous voulons remplacer toutes les images sur une page web, nous devrons d’abord avoir toutes les images sur cette page web. Écrivez une méthode (d’aide) qui renvoie une liste de toutes les images sur une page.

Vous pouvez être tenté d’utiliser jQuery, mais soyez prévenu – incorporer jQuery dans une extension Chrome n’est pas facile, et il y a un moyen de résoudre cela en utilisant vanilla JS. Si vous avez besoin d’un indice, consultez la documentation de querySelectorAll.

Tâche F : Mettre à jour parseSettings pour gérer les règles de remplacement d’image en plus des règles de remplacement de texte.

Vous devrez modifier l’implémentation de parseSettings pour faire attention à la ou aux règles de remplacement d’image. Comment allez-vous représenter une règle de remplacement d’image ?

Tâche G : Mettre à jour la source de chaque image sur la page.

Une fois que vous avez les images et l’URL de remplacement, écrivez du code pour mettre à jour l’image originale afin qu’elle affiche l’URL cible. Si vous avez besoin d’un indice, regardez l’attribut src sur les images.

Tâche H : Nous sommes tous dans le même bateau

Avec ces méthodes d’aide en main, implémentez la fonction replaceAllImages dans src/inject/inject.js. Cette fonction est appelée immédiatement après l’évaluation des remplacements de texte. Si tout va bien, vous devriez pouvoir entrer une règle de remplacement d’image dans l’action du navigateur, et voir que toutes les images sont remplacées !

Félicitations !

Vous avez réussi ! Très bien fait. Vous avez construit une extension chrome cool qui remplace le contenu des sites Web, et qui plus est, vous pouvez la garder!

Prenez un moment pour vous détendre, prenez une profonde respiration, et regardez en arrière sur le projet que vous avez construit. C’est très impressionnant !

Si vous arrivez à ce stade, venez sur le canal Slack #hackpack-chrome-ext pour fêter ça ! Vous le méritez.

Extensions

A un haut niveau, vous avez construit un système qui repose sur le passage de messages entre un dialogue popup (action du navigateur Chrome) et un script qui s’exécute sur chaque page web. Nous avons utilisé cela pour transmettre des informations sur les remplacements de texte et d’image au script d’injection, mais il n’y a aucune raison pour que nous nous arrêtions là !

Vous pouvez étendre ce cadre pour construire des projets vraiment cool. Le ciel est la limite, mais nous avons donné quelques suggestions ici.

• Match plus que du texte brut – match expressions régulières ! Étendez la fonctionnalité de modifyText pour traiter les motifs de settings comme représentant des expressions régulières, pas seulement du texte brut.
• Support de la correspondance sur les sélecteurs de document du DOM. Correspondance sur les noms de balises (comme img, mais aussi a et iframe), ou les noms .class, ou peut-être même #ids. Pouvez-vous construire un support pour l’ensemble complet des sélecteurs ?
• Ne remplacez pas toutes les images – remplacez-en seulement quelques-unes (disons 1%). Pourriez-vous changer les liens youtube (balises a avec un href contenant "youtube") en vidéos de Rick Astley ?

S’éloignant du domaine des remplacements,

• Permettez à l’utilisateur de signaler des informations au script de fond. Peut-être lui demander son nom, et surligner en rouge tout texte qui contient son nom.
• Laisser l’utilisateur spécifier un tas de serveurs pour agir comme des proxies. Vous avez construit un Tor de base !
• Permettez à un utilisateur d’entrer ses données de santé, et suggérez (via une popup amicale ou une redirection) qu’il fasse de l’exercice à chaque période de temps qu’il passe à naviguer sur un site (toussa reddit toussa).

Ce n’est que le début. Laissez libre cours à votre imagination. Nous sommes impatients de voir ce que vous construisez !

Divers

Feedback

Si vous avez des commentaires, positifs ou négatifs, adressez-vous à Sam Redmond (@organizer-sam sur Slack) avec des commentaires ! Nous serions ravis d’entendre ce que vous trouvez génial et ce que vous pensez que nous pouvons améliorer.

Crédit

Le crédit pour l’idée va aux initiateurs de l’extension Chrome Cloud-to-Butt, le crédit pour la grande documentation (dont une grande partie a été volée sans vergogne) va aux contributeurs de Chromium, et le crédit pour les images va à XKCD.

Licence

MIT