3. Chrome Extension Functionality

tags from the current page and inserting our own custom text automatically when the extension is loaded.

Before we begin, create a new folder titled remove_div_tags_from_page and create the empty files shown below:

File Structure

• /remove_div_tags_from_page/
• /remove_div_tags_from_page/manifest.json
• /remove_div_tags_from_page/contentscript.js

File Structure

• /change_words_panel/
• /change_words_panel/manifest.json
• /change_words_panel/side.html
• /change_words_panel/side_script.js
• /change_words_panel/contentscript.js
• /change_words_panel/icon.png

Source: /ch3/change_words_panel

In the extension folder, the manifest.json file is used to define the basic attributes and permissions of the extension. The side.html is a HTML-based user interface that is shown to the user in the form of a side panel in the browser. The side_script.js file is the associated JavaScript for this side panel. The contentscript.js file contains the JavaScript that is run on the current page in the browser to perform the replacement process. The icon.png is the same smiley face icon used throughout this book.

File Name: manifest.json

This file begins with the standard attributes to define the name, description, and version number of the extension. The permissions attribute includes the activeTab permission, as we need to modify the content of the page the user is currently viewing. The scripting attribute is added as the extension executes a script to perform the replacement. The sidePanel permission is added as it allows us to open a side panel on the browser to hold the user interface of the extension. The side_panel attribute is then used to define attributes of the panel itself. In this example, we define the default_path to be side.html, which is a simple HTML file used as the user interface for the extension.

The content_scripts attribute is used to define the URL we wish the extension to run on and the JavaScript file we want to execute on it. The matches attribute defines the specific URL pattern the extension will look for. In this example, we are using the Google.com address, with two asterisks at the start and end of the URL indicating that any of the sub-pages of Google.com * can be included. The js* attribute is used to define the script that we want to execute on the selected URLs.

The action attribute is then added to define the default_title attribute, which shows a simple piece of text when a mouse is placed over the extension's icon. Finally, the default_icon attribute is used to define the default icon for the extension that will show up in the browser's menu bar. In this example, the simple smiley face icon is used.

{
    "manifest_version": 3,
    "name": "Word filter",
    "description": "Word filter",
    "version": "1.0",
    "permissions": [
        "activeTab",
        "scripting",
        "sidePanel"
    ],
    "side_panel": {
        "default_path": "side.html"
    },
    "content_scripts": [
        {
            "matches": [
                "https://*.google.com/*"
            ],
            "js": [
                "content-script.js"
            ]
        }
    ],
    "action": {
        "default_title": "Click to open panel",
        "default_icon": "icon.png"
    }
}

File Name: side.html

The side panel is a simple HTML user interface that is used to display a piece of text to the user in the form of a h1 tag as the panel title. A HTML textarea element is used to hold a list of word and replacement word pairs that the extension will use. The textarea has an ID set to filer_words, which will be used in the future when we need to select the textarea to get access to the word pairs.

In this textarea, by default, four sample words are added. Each new word pair to replace is on a separate line, as when the extension executes the replacement process, it will treat each new line as a separate word pair. Between each original word and replacement word, an equals sign is added to indicate they are a pair. The main trigger for this extension is the HTML button with the ID set to myButton. When this is clicked, the process of executing the filter is performed to replace the terms on the current webpage.

At the end of this file, a <script> tag is included, which points to the JavaScript file titled side_script.js that contains additional JavaScript for the extension. This <script> tag is added here as no JavaScript can be directly added to a HTML file.

<h1> Word filter list</h1>

<textarea id="filter_words" rows="10" cols="40">
Google=GOOGLE
second=2nd
third=3rd
fourth=4th
</textarea>

<button id="myButton"> Run filter </button>

<script src="side_script.js"></script>

In the future, when the user wishes to add another word pair, they can add a new line into the textarea on the side panel in the browser.

File Name: side_script.js

As no JavaScript could be added directly to the HTML user interface file, at the end of the file, a <script> tag was added which pointed to the side_script.js file. Inside the file, the querySelector is used to select the button we created earlier with the ID myButton. Using this button reference, the addEventListener() function is added to the listener for clicks. When a click is performed on the button, the body of the function is run. Inside this, a small message is printed to the developer console indicating the button has been clicked.

The getElementById() selector is then used to select the filter_words attribute (which is the textarea) and extract the value from it. The terms are then placed into a local variable titled wordsString, which is then printed to the console. After this, a call is made to the runProcess() function, and the word list is passed to it. This is the main replacement function that is responsible for taking a list of words and replacements words in, and running the replacement process.

let btn = document.querySelector("#myButton");

btn.addEventListener("click", function () {
  console.log("main button clicked");

  let wordsString = document.getElementById("filter_words").value;
  console.log(wordsString);

  runProcess(wordsString);
});

To create this function, a new function definition is then added titled runProcess(). This function is an asynchronous function designed to run in the background without holding up the extension. In this, a console.log() is added to print to the developer console that we have reached this location in the code to aid debugging. As users often have many different tabs open, we need to get the tab that was in focus in the user's browser. This tab contains the web page to perform the replacement on. To do this, a call is made to the await chrome.tabs.query() function, which is passed the two parameters active: true, lastFocusedWindow: true to tell the browser to give us a reference to the last focused tab. This reference is then placed into a local variable titled tab.

When working in a restricted environment, such as browser extensions, the abilities of JavaScript can be quite limited, and the panel itself cannot run the replacement process. For this reason, we need to send a message from the panel across to the web page to tell it to run the replacement process. To do this, a call is made to the chrome.tabs.sendMessage() function to send a message from the extension across to the web page we want to modify in the user's browser. Three core pieces of information are passed to the function. The first is the tab.id which contains the ID of the tab we want to send the message to, second is a custom piece of JSON we will send that indicates to the extension we wish to run the filter, and third, a variable titled words which has the value set to the list of words we gathered from the textarea in the form of a variable titled wordsString. Although unused, the result of calling this function is placed into a variable titled response.

  console.log("in runProcess async");
  const [tab] = await chrome.tabs.query({
    active: true,
    lastFocusedWindow: true,
  });

  const response = await chrome.tabs.sendMessage(tab.id, {
    status: "run_filter",
    words: wordsString,
  });
}

File Name: content-script.js

Now that we have the side panel user interface set up with a list of replacement terms and a method of triggering the process in the form of a button, we can begin the process of implementing the actual replacement script itself. This script is designed to wait for the message that is sent across from the panel to the content script to run the replacement when the button is clicked. This content-script.js file is designed to run on the web page itself, and has access to the DOM tree of the web page. In this file, a console log is added to indicate that the file has loaded correctly. After this, the chrome.runtime.onMessage.addListener() function is added. This allows the code to listen for incoming messages that are sent across from the panel.

When a message is sent across, the listener is triggered, and this function has access to three references. The first is the request, which contains all the data that was sent across, the second is the sender variable, which outlines which tab sent the message, and the third is the sendResponse function reference, which can be used if we wish to send a message back. Inside this function, a console log is used to print the value of the request to the developer console, which contains the terms sent across to aid debugging.

chrome.runtime.onMessage.addListener(

function(request, sender, sendResponse) {

console.log(request);

An if statement is then added to check if the request.status sent across was equal to run_filter. This status attribute was contained in the JSON sent across by the panel. In the case where this is true, a console.log() is used to print a message to the developer console indicating that the filter is being run. A call is made to the processWords() words. This function takes in the request.words attribute, which contains the list of words and their replacements. When this function is run, the individual word pairs in the form of strings represented as word=replace on separate lines are then broken into key-value pairs. The final set of processed key-value pairs is placed into a local variable titled pairs.

A for loop is then used to loop over each of the words and their replacement words as key-value pairs. For each of these pairs, they are first printed to the console using a console.log() call, and then a call is made to the replaceText() function, which is used to perform the actual replacement process of terms on the web page the user is viewing. This function takes in three parameters. The first is document.body, which is the HTML of the web page the user is viewing. The second is the key, which is the word the user wants to replace, and the third is the value, which represents the word it will be replaced with. After the for loop has finished, all the words on the web page will have been replaced with their updated replacements.

console.log("running filter");

let pairs = processWords(request.words);

for (const [key, value] of Object.entries(pairs)) {
    console.log(`${key}: ${value}`);
    replaceText(document.body, key, value);       
}
}

}//listener function
); //listener

The above piece of code is dependent on a function titled processWords(). This function receives a raw list of words extracted from the text area on the panel. As mentioned before, these words are represented as originalWord=newWord. And each set of replacement words is separated onto individual lines. To process these terms into simple key-value pairs, we first create a new array titled pairs. After this, we take the wordList, which contains the raw list of words on separate lines, and split the list of words based on the n character, which separates each word into an individual slot of the array titled items. A call is then made on the items in the array using a forEach loop. In this, while looping over each item in the array, a variable titled singleItem is available.

An if statement is then used to check if the singleItem contains an equals sign. If this returns true, this would indicate that we have a word and its replacement. A console log is then performed to print the complete word pair to the developer console to aid debugging. After this, we need to separate the word and the replacement word and place them into variables titled key and value. To do this, the singleItem variable is first accessed, and a call to the split() function is performed on it. This takes a reference to the parameter we wish to separate the variable on, which in this case is an equals sign. When this is performed, as we want to extract the word first, we call [0] to access just the word by itself and place it into the key variable.

After this, the process is repeated again for the replacement word, but this time the second variable in the array is accessed using [1] to extract the new replacement term and place it into a variable titled value. As we now have the key variable and the value variable separate, a call is made to the pairs array and the value is placed into the array at position key. This is then performed for each of the word pairs in the list to fully populate the pairs array. At the very end of this process, we finally called the return function to send back the complete pairs array.

  console.log("Processing words");
  let pairs = {};

  let items = wordsList.split("\n");

  items.forEach((singleItem) => {
    if (singleItem.includes("=")) {
      console.log(singleItem);

      key = singleItem.split("=")[0];
      value = singleItem.split("=")[1];

      pairs[key] = value;
    }
  });

  return pairs;
}

If the pairs array that was returned when the processWords() function is finished was viewed, it would contain four entries in the array as shown below. This array provides a simple structure to move the words and their replacements around. In the next step, this array will be looped over, and each word will be replaced with its corresponding replacement word in the array.

pairs[second]  = 2nd
pairs[third]   = 3rd
pairs[fourth]  = 4th

At the end of this file, we add a function titled replaceText() which is responsible for performing the actual replacement process of the words. This function works by calling itself to iterate through the DOM tree. When this function is called, three references are available. The first is the node reference, which is the location in the web page's DOM tree where the replacement will be performed. The second is the key, which is the word we wish to replace. And finally, the third is the value, which is the word we are replacing the key with. In this function, an if statement is used to check if the node.nodeType we are currently looking at is a TEXT_NODE. If this returns true, the replacement process is performed. This is done by creating a new RegEx object, which is passed a pattern to search for the key representing the word we are looking for in the web page.

After the RegEx is created, it is placed into a variable titled regex. Next, a call is made to the node.textContent, which represents the raw text of the word we are replacing. We then call node.textContent.replace() to perform the replacement by passing in the reference to the regex which contains the word location and the value indicating the replacement word.

In the case where the if statement does not find the term, the else statement triggers, in which a loop is used to loop through each child node the current node has. It then makes a call to the replaceText() function to be called again to retry the entire process on the child node found. It is important to remember here that the innerHTML element is not used during the replacement process, as when this is called, it causes the entire page to be parsed again, often returning errors.

  if (node.nodeType === Node.TEXT_NODE) {
    const regex = new RegExp(`\\b${key}\\b`, "gi"); // case-insensitive match for whole words
    node.textContent = node.textContent.replace(regex, value);
  } else {
    for (let child of node.childNodes) {
      replaceText(child, key, value);
    }
  }
}

View Results

In Figure 10, the content of the browser side panel can be seen. Individual words are shown to the right. Inside this, the key-value pairs are added in the form of the original word, followed by an equals sign, followed by the new replacement word.

Figure 10: Word filter panel content containing the words we want to replace and their replacement words.

In Figure 11, the console output from the extension can be seen. At the top, the JSON sent from the side panel to the content script can be seen. This is performed as the side panel does not have access to the webpage itself. The command we wish to run is contained in the status attribute of this JSON. The words attribute contains all the raw text with new line characters from the textarea that was extracted. When the extension is run, the replacement process is performed on each key-value pair. The output of this process can also be seen.

Figure 11: Word filter console output.

Figure 12 shows the panel on the right of the browser and the Google homepage on the left. On the webpage, you can see that the word Google on the button has been replaced with GOOGLE by running the extension.

Figure 12 Side filter panel opened after running on the Google.com homepage.

3.6 Summary

This chapter introduced the basic functionality of Chrome extensions by performing actions such as modifying the webpage the user is currently viewing. This was done in two different formats: automatically when the extension is loaded, and also dynamically as a result of user interaction. The side panel was also introduced as a simple method of containing a user interface that is always available to the user.

Chapter 4, next, furthers the development process by exploring full-stack extensions and the technologies required.