De-mystifying the age old Chrome extensions

A brief of all Chrome extension tools and my experience building Clean Theme extension

I have been fangirl-ing Harley Quinn of DC Comics for a long time now and after watching the Suicide Squad movie, my obsession hit the next level. All I wanted was to start my daily life with her, one tab at a time! So, I got my favourite comic character Harley themed background on my favourite browser Chrome. But, this is what Chrome decided to give me on my new tab. Harley covered by the Google logo, search bar and thumbnails [tons & tons..well, just 8 but they were enough to cover Harley completely! :( ] While I understand the utility of these features, Chrome should really start taking subjective preferences into consideration. Anyways, desperate attempts to clean up this page started my Chrome extensions journey.

New tab page before adding clean theme chrome extension

The extension I built, Clean Theme, hides the default Chrome new tab elements so that you can see your background themes in full glory. You can play around with the code hosted at git. Here I would like to document a few main features of extensions and my journey of building this extension.

New tab page after adding clean theme chrome extension

Chrome extensions are easy!

All you need to know to build a Chrome extension is our basic HTML, JS and CSS. Extensions are simple web pages running on the browser adding extra functionality to it.

Chrome extensions are fun!

Personally building an extension was really fun. Extensions are like hacks we apply on already existing huge ecosystem of browser components to introduce our features and when wasn’t hacking fun?! :) It lets you find creative ways of tweaking the tightly interwoven web of browser.

Chrome extensions are structured!

Browser gives us specific entry points and APIs to add our extension to its ecosystem. Knowing these can greatly save your time in understanding what functionalities can/cannot be added and what gateways work best for you. The Clean Theme extension took me 4 hours to build which would have otherwise taken 15 mins to build if I had the prior knowledge.

Chrome extensions are easy to test & debug!

1. Goto chrome://extensions
2. Tick the ‘Developer Mode’ on top right corner
3. Click ‘Load unpacked extension..’ and select the extension folder

That’s it! Your extension is locally added and can be tested on your browser.

Extensions’ architecture

manifest.json

This is a json which gives all important information about the extension (name, version, icons), permissions it will need from the browser and the capabilities of the extension. This is the manifest.json file of Clean Theme.

{
  "manifest_version": 2, //version of manifest file format
  "name": "Clean Theme", 
  "short_name": "CT", 
  "version": "1.0", 
  "description": "Hides all the default google new tab elements     blocking the background theme", 
  "browser_action": {    
     "default_icon": "icon.png",    
     "default_title": "Cleans up your chrome theme!"
  },
  "content_scripts": [
     {
       "matches": [
           "*://*/_/chrome/newtab*"
        ],
        "js": [
           "content.js"
        ],
        "run_at": "document_idle"
     }
   ]
}

Other noteworthy keys of manifest.json are

{
  "page_action": {...},
  "background": {
    "persistent": false
  },
  "chrome_url_overrides": { //lets you override any 1 of the 3 pages
    "bookmarks": "example.html" OR
    "history": "example.html" OR
    "newtab": "example.html"
  },
  "commands": {...}, //give keyboard shortcuts to trigger actions in your extension
 
 "devtools_page": "devtools.html", //adds functionality to devtools
  "event_rules": [{...}], //add rules that intercept, block, or modify web requests
 
 "incognito": "spanning, split, or not_allowed",
  "offline_enabled": true, //enable running in offline mode
  "omnibox": { //let Google search bar send input to your extension after entering the keyword
    "keyword": "aString"
  },
 
  "permissions": ["tabs"],
}

browser_action

Browser actions let you put an icon to the right of the address bar in the toolbar. Additionally, it can have a tooltip, a badge or a popup. A tooltip is specified by ‘default_title’ in the manifest file. A badge can be at max of 4 characters and can be used to specify the state of the extension. A popup shows up when the extension icon is clicked. It is specified by ‘default_popup’ in the manifest file and points to a HTML file.

page_action

Page actions are similar in UI to browser actions but are used when you want to activate the extension based on the current page. Use ‘hide’ API to deactivate the extension when not required.

content scripts

If you want to interact with the content of the web page after it is loaded, use content scripts. The ‘matches’ keyword in manifest file specifies array of webpage URL regexes into which the content script must be injected. The JS and CSS files are specified with the respective keywords. The ‘run_at’ keyword tells the browser when to inject the files. The following flame chart views demonstrate the differences.

content script inserted at document_start

• document_start: files are injected after all CSS files but before DOM construction or any other script execution.
• document_end: files are injected when immediately after DOM construction but before downloading any resources like images.
• document_idle: files are injected between document_end and immediately after window.onload event fires.

content script inserted at document_end

background pages

interaction between pages (source)

Background pages are single instance tasks running in the process of the extension. They run for the lifetime of the extension and are generally used to keep track of state changes. Other pages request the state from background pages or the background pages might notify other pages when a state changes.

interaction with content script (source)

While content script cannot change the DOM of the parent extension pages, it can always send/receive messages from the parent extension. Background page might ask content script to change current webpage DOM or content script might notify background page of webpage DOM elements or changes in them.

The scripts might not always be required to run in the background and making persistent key to false in manifest file lets you make these background scripts event driven.

permissions & Chrome.* APIs

Chrome.* APIs are Chrome only APIs that allow tight integration with the browser. You can detect things like if a new tab is created or if URL in the address bar is changed. Most of these APIs are asynchronous calls, so make sure to write callbacks. Permissions keyword in manifest file requests permissions to access these APIs.

Clean Theme

Since I wanted to change the new tab I first started off with the ‘chrome_override_pages’ only to realise that these pages completely override the new tab including the background theme. Then I proceeded to write event driven background pages and saw that these pages don’t have access to the webpage DOM. This finally pivoted me to the content scripts which can actually manipulate the DOM of the page using which I accessed and hid all unwanted elements to see Harley in full glory! :) Since I didn’t want to interrupt with other new tab extensions functionalities, I only caught each unwanted element and hid it leaving the DOM intact.

Deployment

Compress your extension folder into a .zip file, goto developer dashboard and add new item. The first addition costs a one time $5 setup cost. Just follow the instructions in the form and your extension will be live in no time! :)