{dev_notes}

Google Chrome Extensions

Published 3 years ago.
Last updated

About

Extensions are small event-based software programs that tailor the functionality and behavior of the Google Chrome browser.

Extensions are built with HTML, JavaScript, and CSS, and work by listening for events, or browser triggers, such as clicking the extension icon, navigating to a new page, downloading a file, removing a bookmark, or closing a tab. Extensions monitor these events and when they happen, react with specified instructions.

All file assets for an extension are zipped into a single .crx package that users download and install. This means extensions do not depend on content from the web, unlike ordinary web apps.

A Chrome extension consists of three parts:

  • Popup
    The UI seen when the icon for the extension is clicked.
  • Content Scripts
    Scripts that run on top of existing web pages.
  • Background Scripts
    Scripts that run in the background of Google Chrome.

These individual parts live in their own scopes. They are fully sandboxed, have no knowledge of one another and, as a result, cannot directly access each other. However, information can be passed between the parts via the Chrome API.

Project Directory

Extensions which are in development keep their files in a project directory which can reside anywhere on the development system.

The only required file is manifest.json, all other extension files can be named anything and can exist directly in the project directory or in any directory beneath it.

manifest.json File

https://chrome-apps-doc2.appspot.com/extensions/manifest.html

The manifest.json file sits in the root of the project directory and defines the settings and file paths for scripts and other files used by the extension.

For security, in-line JavaScript is forbidden. All JavaScripts must be placed in a .js file somewhere under the project directory and referenced in the manifest.json file.

Extension Manager Page

Extensions which are in development need to be refreshed each time a change is made. Extensions can be loaded, unloaded and refreshed from the Extension Manager page.

Go to the extension manager page in the Chrome browser: chrome://extensions/

To load the extension into Chrome, click the Load unpacked button and when prompted, navigate to the extensions local project directory.

While developing, if changes are made, the extension needs to be reloaded from this page using the refresh button. Any extension errors can also be found here.

Sometimes critical errors cause the extension to lock-up or break, and may need to be unloaded, and then loaded again to clear all of its parts from memory.

General Info

The most basic extension requires only that a manifest.json file exist in the root of its project directory. The name, version, and manifest_version keys are the only required setting in the file:

{
    "manifest_version": 2,
    "name": "Example Chrome Extension",
    "version": "1.0"
}
Property Description
manifest_version Required: Which version of the manifest file is the extension using?
name Required: The name of the extension.
version Required: The version number of the extension.
description Optional: A brief plain-text description of the extension.
default_locale Optional: en is the default.
icons Optional: The file paths to one or more icons that represent the extension.

Popup

https://developers.chrome.com/extensions/user_interface#popup
https://developers.chrome.com/extensions/browserAction
https://developers.chrome.com/extensions/pageAction

The Popup is the UI which opens when the icon for the extension is clicked. The popup window content is a fully-realized webpage and automatically sized to fit its contents. It’s built with HTML, CSS and JavaScript. The only difference between a webpage and a Chrome extension popup, is that the HTML file must be registered in the manifest.json file.

Note: Each time the popup is closed, it’s as if the webpage were closed, everything that was stored in memory is lost.

browser_action

The Popup is managed by the chrome.browserAction API. Settings are defined under the browser_action key in the manifest.json file.

{
    "name": "My extension",
    ...
    "browser_action": {
        "default_icon": {                    // optional. Icons specific to the toolbar.
            "16": "images/icon16.png",       // optional
            "24": "images/icon24.png",       // optional
            "32": "images/icon32.png",       // optional
           "128": "images/icon128.png"       // optional
        },
        "default_title": "Google Mail",      // optional; shown in tooltip
        "default_popup": "popup.html"        // optional
    },
    ...
}
Property Description
default_popup The HTML file to open as the UI when the extension icon is clicked.
default_icon Icons specific to the toolbar. Including multiple sizes is encouraged. At minimum, 16×16 and 32×32 sizes are recommended.
default_title The tooltip or rollover text of the extension icon.

Including multiple sizes is encouraged to scale for the 16-dip space. At minimum, 16×16 and 32×32 sizes are recommended.

popup.html

<!doctype html>
<html>
    <head>
        <title>My extension</title>
        <script src="js/popup.js"></script>
        <link rel="stylesheet" type="text/css" href="css/popup.css">
    </head>
    <body>
        <h1>My extension</h1>
        Hello, World!
    </body>
</html>

Icon Badges

Browser actions can optionally display a badge — a bit of text that is layered over the icon. Badges make it easy to update the browser action to display a small amount of information about the state of the extension.

Content Scripts

https://developer.chrome.com/extensions/content_scripts

Content Scripts contain JavaScript that executes in the contexts of a page that has been loaded into the browser, as if they were shipped with the website itself.

These scripts have access to everything in the DOM. They can read and write to web pages

content_scripts

content_scripts defines the URLs on which the extensions JavaScript and CSS files are injected by the extension. By using the DOM, injected JavaScripts are able to read details of the web pages the browser visits, make changes to them and pass information to their parent extension.

"content_scripts": [
  {
    "matches": ["<all_urls>"],
    "css": ["background.css"],
    "js": ["background.js"]
  }
],
Property Description
matches Required: array of strings
Specifies which URLs this content script will be injected into.
To inject on all sites: "matches": ["<all_urls>"]
Regex can be used for URL values.
To inject on a single site, like Twitter for example: "matches": ["https://twitter.com/*"]
Chrome will grey-out the extension icon when it’s inactive.
css Optional: array of strings
The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page.
js Optional: array of strings
The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.
match_about_blank Optional: boolean
Whether the script should inject into an about:blank frame where the parent or opener frame matches one of the patterns declared in matches. Defaults to false.

Background Scripts

background

"background": {
    "scripts": ["background.js"],
    "persistent": false
},

Permissions

https://developer.chrome.com/extensions/declare_permissions

Many of the APIs Chrome exposes for extensions require permissions. Most APIs must be registered under the “permissions” field in the manifest for the extension to use them.

The permissions needed depend on what the extension needs to do.

Permission Description
activeTab Required to get the URL of the current tab. 
"permissions": [
    "activeTab"
]

Chrome APIs

https://developers.chrome.com/extensions/api_index
https://developers.chrome.com/extensions/devguide

Scripts can tap-in to the browser functionality and behavior using the Chrome APIs.

Most APIs must be registered under the “permissions” field in manifest.json for the extension to use them.

API Description
Messages The Messaging API contains all the methods used for the exchange of messages within the extension ecosystem and doesn’t require any permissions.
Tabs The Tabs API allows you to interact with all the tabs that a particular chrome window has opened.

Examples

Open the popup with a keyboard shortcut

Place in the root of the

"commands": {
    "_execute_browser_action": {
        "suggested_key": {
            "default": "Ctrl+Shift+F",
            "mac": "MacCtrl+Shift+F"
        },
        "description": "Opens the extension popup"
    }
}

More Resources