Dissenter Browser Extension

This repository holds the Dissenter Browser Extension code that is used to generate the final distribution code per each browser.

For more information, please visit: https://dissenter.com

• Download the Dissenter Browser Extension

Please head over to https://dissenter.com/download to download the extension for your specific browser and view detailed installation instructions.

• Installation

Latest versions:

This extension only requires developer dependencies.

Clone or download the repository and then: $ npm install

• Overview

This is meant to help anyone understand this repository, where everything lives and what everything does.

• Details

This extension is comprised of a configuration class (Browser) and its corresponding extension files. The extension files follow the standard browser extension layout: manifest, popup, background, and other related browser API's to connect them all.

For more information regarding the understanding of how browser extension source code is formatted please visit: https://developer.chrome.com/extensions/getstarted or https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons

Chrome, Firefox, and Microsoft edge share nearly identical browser extension API's. Within the following sections, we'll touch upon shared code and how we use gulp, an automation toolkit, to inject the configuration class (Browser) specific variables into the code base in order to achieve the final distribution code per each browser.

Safari browser extensions can be created via Extension Builder and by following "Chrome Extension Porting" instructions detailed here: https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/SafariExtensionsConversionGuide/Chapters/Chrome.html. For the most part however, Safari extensions contain similar code to the previously mentioned browsers.

• Code

The code is split into the configuration and source folders.

• Configuration (./config)

The configuration files contain the Browser class (browser.js), browsers that implement the Browser class (browsers.js) and the manifest file (manifest.js) that all browser extensions rely on.

The Browser class contains information that the Build Process uses. Aside from name, slug, version, and path, the manifestMap and scriptVariableMap are what we use to customize the source code and manifest.

• manifestMap

The manifestMap is an object that contains key/value content that is used to inject into the manifest file. Within the gulp:manifest function, we grab the ./config/manifest.js file, clone it, convert to JSON then inject the browser.manifestMap object into it.

This is necessary because each browser may require seperate key/values or, are simply just named differently.

• scriptVariableMap

The scriptVariableMap is an object that contains key/value content that is used to define browser specific variables using general variable names.

The existing values that we use are:

Each of these variables in the scriptVariableMap are used within the Build Process to find and replace throughout the code. This enables us to write 1 (one) shared codebase for all of these browser extensions by just writing generic variable names such as __BROWSER__ and within the gulp process, using the Browser class, we replace all occurences within each source file.

Example:

//Before
__BROWSER__.browserAction.onClicked.addListener(function() {
    // some code here...
});

Running the gulp:scripts function provides the following output for example:

//After
myCustomBrowserVariable.browserAction.onClicked.addListener(function() {
    // some code here...
});

• Source (./src)

The source files contain folders for images, scripts, styles and views.

• Images (./src/images)

The images are split up between icons and logo. The images are used within some of the styles and views files.

• Scripts (./src/scripts)

We're using vanilla javascript for these files. We don't use any module bundlers anything for this other than uglifcation. The scripts are seperated between background, components and utils.

The scripts are split up during the build process between: background.js, popup.js. Each of those files do not contain each other but, they do however contain all of the util directory files.

• Styles (./src/styles)

We use scss for our styles.

The style files are split up using a standard scss organizational structure of components, modules, and partials. During the build process each of the components (currently only: popup.scss) contain all of the modules and partials styles. The components do not share code between themselves.

• Views (./src/views)

We use pug (https://pugjs.org) for each of the views files.

• Build Process

The build process uses each Browser class object defined in ./config/browsers.js to automatically build scripts, styles, html, manifest and images into the ./build directory (hidden). The gulp scripts compile, minify (& mangle) and save the combined files in these ./build directories.

Each of those scripts can be run using npm.

For example:

$ npm run gulp:scripts
$ npm run gulp:styles
$ npm run gulp:html
$ npm run gulp:manifest
$ npm run gulp:images

You can also run all of them at once using the gulp build function:

$ npm run build

During the build process, all of the code in the ./src directory is compiled into the ./build directory. The ./build directory will contain folders named after each of the Browser class slug (browser.slug ... i.e. chrome, firefox, etc.). Each of the folders contain browser specific extension code formatted in a specific way that is read by the main manifest.json in each of the folder's directories. For example, the popup, images, background and other related manifest.json keys are transfered from the ./src directory into the ./build/* folders.