DEV Community: Simon Cleriot

Build a Firefox extension step-by-step

Simon Cleriot — Fri, 06 Apr 2018 15:54:23 +0000

Lately I've been using the reading list on dev.to. It's a nice tool, but I'm used to saving articles for later in Pocket.
In this article, we're going to create a Firefox extension to automatically add a post to your Dev.to reading list and your Pocket account at the same time.

Here is what it looks like (the extension file is available at the end of this article):

The extension expects you to be already connected to a Pocket account in your browser (so we don't have to handle API authentification).

What is a browser extension?

A browser extension is a collection of scripts executed when Firefox browses to specific pages. Those scripts can alter the HTML, CSS and JavaScript of a page, and have access to specific JavaScript APIs (bookmarks, identity, etc...).

There are two types of scripts: content and background. Content scripts are executed within the page whereas background scripts perform long-term operations and maintain long-term state. Background scripts also have access to all the WebExtension API.

Here is the final file structure for this project:

manifest.json (configuration file)
background.js (our background script)
devtopocket.js (content script executed on the dev.to page)
images/

Content and background scripts

We have two scripts in our project: one that handles background work (sending the Ajax request) and another one (a content script) that registers a click event on the "Reading list" Dev.to button:

Content script

The content script (devtopocket.js) registers the click and sends the request to our background script.

devtopocket.js

document.getElementById("reaction-butt-readinglist").addEventListener("click", function() {
    if(window.confirm("Do you want to save this article in Pocket?")) {
        sendBackgroundToPocket();
    }
});

The sendBackgroundToPocket method needs to communicate with the background script and ask it to send the Ajax request.

browser.runtime gives us a two way communication channel between our extension scripts. browser.runtime.sendMessage sends a message on that channel and returns a Promise that waits for a response on the other side. Once we get the answer (meaning the Ajax request has completed), a message is displayed to the user (cf the above gif):

devtopocket.js

function sendBackgroundToPocket(){
    browser.runtime.sendMessage({"url": window.location.href}).then(function(){
        document.getElementById("article-reaction-actions").insertAdjacentHTML("afterend", "<div id='devtopocket_notification' style='text-align: center;padding: 10px 0px 28px;'>This article has been saved to Pocket!</div>")
        setTimeout(function(){
            document.getElementById("devtopocket_notification").remove()
        }, 2000)
    });  
}

Background script

A background script is used to write time consuming operations that do not depend on a specific web page being opened.

These scripts are loaded with the extension, and are executed until the extension is disabled or uninstalled.

Our background script (background.js) has two roles:

Sending the Ajax request
Reacting to URL changes via History API

In the extension configuration (manifest.json below), we're going to say "load devtopocket.js on pages matching an url pattern" and it works when we browse straight to an article page.

The "issue" with dev.to website is that it uses HTML5 History api to browse pages (as does every single page webapp). Firefox doesn't listen for url changes if the page isn't fully reloaded and therefore doesn't execute our content script. That's why we're going to need a background script to listen for url changes via History API, and manually execute the frontend script when needed.

We listen to url changes by using the webNavigation API:

background.js

browser.webNavigation.onHistoryStateUpdated.addListener(function(details) {
    browser.tabs.executeScript(null,{file:"devtopocket.js"});
}, {
    url: [{originAndPathMatches: "^.+://dev.to/.+/.+$"}]
});

{originAndPathMatches: "^.+://dev.to/.+/.+$"} restricts the listener to a specific target url pattern (the same as the one we're also going to define in our manifest.json).

The browser.tabs.executeScript method loads a content script in the current tab.

The background scripts expects a message from our content script (when the "Reading list" button is clicked):

background.js

function handleMessage(message, sender, sendResponse) {
    if(message.url) {
        sendToPocket(message.url, sendResponse)
        return true;
    }
}
browser.runtime.onMessage.addListener(handleMessage)

The sendToPocket method is called upon message receiving.
To save our url in Pocket, we're going to call the existing save page provided by Pocket (https://getpocket.com/save). A classic Ajax request will do the trick:

function sendToPocket(url, sendResponse) {
    var xhr = new XMLHttpRequest();
    xhr.onreadystatechange = function(){
        if(xhr.readyState === XMLHttpRequest.DONE && xhr.status === 200) {
            sendResponse();
        }
    };
    xhr.open("GET", "https://getpocket.com/save?url="+url, true);
    xhr.send();
}

You might see coming the Cross Origin Request problem, we'll address it later with the extension permissions.

The manifest

manifest.json is our extension configuration file. It's like a package.json in a javascript webapp or an AndroidManifest.xml in an Android app. You define the version and name of your project, permissions that you need and JavaScript source files that compose your extension.

First we write the app definition:

{
    "manifest_version": 2,
    "name": "DevToPocket",
    "version": "1.0.0",

    "description": "Send your DEV.to reading list to Pocket",

    "icons": {
        "48": "icons/devtopocket-48.png"
    },
    ...
}

Supply at least a 48x48 icon, if you supply more sizes Firefox will try to use the best icon size depending on your screen resolution. We're going to use this icon:

icons/devtopocket-48.png

Then we define our permissions:

{
    ...
    "permissions": [
        "storage",
        "cookies",
        "webNavigation",
        "tabs",
        "*://dev.to/*/*",
        "*://getpocket.com/*"
    ]
}

You can find the permissions list in the Mozilla documentation.

URLs in the permissions gives our extension extended privileges. In our case, it gives us access to getpocket.com from dev.to without cross-origin restrictions, we can inject a script in dev.to via tabs.executeScript and we have access to getpocket.com cookies so the Ajax request is authentificated. The full host permissions list is available here.

The full manifest.json file:

{
    "manifest_version": 2,
    "name": "DevToPocket",
    "version": "1.0.0",

    "description": "Send your DEV.to reading list to Pocket",

    "icons": {
        "48": "icons/devtopocket-48.png"
    },

    "content_scripts": [
        {
            "matches": ["*://dev.to/*/*"],
            "js": ["devtopocket.js"]
        }
    ],
    "background": {
        "scripts": ["background.js"]
    },

    "permissions": [
        "storage",
        "cookies",
        "webNavigation",
        "tabs",
        "*://dev.to/*/*",
        "*://getpocket.com/*"
    ]
}

Run the extension

In order to run your extension, we are going to use the web-ext command line: https://github.com/mozilla/web-ext

This is a command line tool to help build, run, and test WebExtensions.

npm install --global web-ext

Then in your terminal, run the following command in your project folder:

web-ext run

It's going to launch a browser with your extension temporarily loaded. The extension is automatically reloaded when you make some changes.

Sign the extension

To install your extension in someone else's browser, you'll need to package and sign the extension.

First create a developer account on the Mozilla Developer Hub then retrieve your API credentials here: https://addons.mozilla.org/en-US/developers/addon/api/key/

Run the web-ext sign command:

web-ext sign --api-key=user:XXX --api-secret=YYY

Your extension file will be available afterwards in web-ext-artifacts/devtopocket-X.X.X-an+fx.xpi. Open the file in Firefox to install it.

The complete source code is available on GitHub: https://github.com/scleriot/devtopocket
You can download and install the latest release: https://github.com/scleriot/devtopocket/releases/latest

This extension also works with Firefox for Android!

TypeScript method decorators example

Simon Cleriot — Sun, 25 Mar 2018 09:12:11 +0000

Decorators are a stage 2 proposal for JavaScript already available as an experimental feature in TypeScript.

A decorator is a function that applies to a class, method, property or parameter and adds some logic to the latter. In other word, using a decorator is the same (but far simpler) as creating a new class that extends the target class and has a field pointing to it:

Source: https://en.wikipedia.org/wiki/Decorator_pattern

You can have even have decorator factories that customize how the decorator is applied to a declaration (making it more easily reusable in different contexts).

In this example, we're going to use a method decorator factory to debounce a function.

Debounce concept

The perfect example for debounce is a realtime-search text input : in order to make a search, you send a request to the server. The naive implementation would send a request each time the text input changes, but it would overload the server and the view would have to wait for every request to finish before displaying the final results.

Debouncing delays the execution of a method for a fixed duration. If the method is called again while being stalled, the first method call is canceled. That way, the search component would only send one request to the server, when the user stops typing.

Which ultimately looks like this:

TypeScript configuration

Decorators are still an experimental feature in TypeScript so you need to explicitly enable experimentalDecorators compiler option. Two possibilities there, depending on how you're building your project:

Command line:

tsc --target ES5 --experimentalDecorators

tsconfig.json:

{
    "compilerOptions": {
        "target": "ES5",
        "experimentalDecorators": true
    }
}

Create the decorator

A decorator factory is declared as a normal TypeScript function :

function Debounce(wait:number, immediate:boolean=false) {

wait is the millisecond delay.
immediate sets if we want to "call the function then stall for x milliseconds before allowing it to be called again", or "stall for x milliseconds then actually call the function".

The Debounce method is going to return the decorator function (that's why it's called a factory):

return function(target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) {

This function gets its three parameters from the element it's applied on (in our example it's going to be the method we want to debounce):

target references the element's class. It will be the constructor function for a static method or the prototype of the class for an instance member
propertyKey is the name of the element
descriptor is the Property Descriptor of the method, so we can alter it

The body of the decorator function looks like this:

var timeout:any;
var originalMethod = descriptor.value;
descriptor.value = function() {
    var context = this
    var args = arguments;
    var later = function() {
        timeout = null;
        if (!immediate) originalMethod.apply(context, args);
    };
    var callNow = immediate && !timeout;
    clearTimeout(timeout);
    timeout = setTimeout(later, wait);
    if (callNow) originalMethod.apply(context, args);
};
return descriptor;

We store the original body of the method:

var originalMethod = descriptor.value;

Then we change it by setting descriptor.value to a new function:

descriptor.value = function() {

We then use timeouts to delay the method execution.

The value returned by our method decorator will override the original class method's descriptor.

In the end we have the following debounce decorator factory:

function Debounce(wait:number, immediate:boolean=false) {
    return function(target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) {
        var timeout:any;
        var originalMethod = descriptor.value;
        descriptor.value = function() {
            var context = this
            var args = arguments;
            var later = function() {
                timeout = null;
                if (!immediate) originalMethod.apply(context, args);
            };
            var callNow = immediate && !timeout;
            clearTimeout(timeout);
            timeout = setTimeout(later, wait);
            if (callNow) originalMethod.apply(context, args);
        };
        return descriptor;
    }
};

Use it

We want to debounce the following search method (from a Vue.js component's class):

search(query: string) {
    axios.get(`users`, {
        params: {
            name: query
        }
    })
    .then(response => {
        // ...
    })
}

We simply apply our previously defined decorator, with the right amount of time:

@Debounce(500)
search(query: string) {
    axios.get(`users`, {
        params: {
            name: query
        }
    })
    .then(response => {
        // ...
    })
}

And that's it, the search method is going to be called only if no other search call is sent during 500ms.

You should definitely consider using Vue.js with TypeScript, they're a great match!
https://fr.vuejs.org/v2/guide/typescript.html

To dig deeper into TypeScript decorators:
https://medium.com/google-developers/exploring-es7-decorators-76ecb65fb841
http://www.typescriptlang.org/docs/handbook/decorators.html
http://www.sparkbit.pl/typescript-decorators/
https://cabbageapps.com/fell-love-js-decorators/

Originally published on my personal blog.

Video.js: frame-accurate subtitles

Simon Cleriot — Sat, 30 Dec 2017 11:03:48 +0000

In the post-production and broadcast industry videos are processed frame by frame.
Subtitles follow the same rule : in and out timecodes are frame accurate (ex: 00:00:23:22 -> 23 seconds and 22 images).

Browsers process videos with millisecond timestamps, that's why subtitles have to be converted based on video framerate: for video at 25 images per second the previous timecode would look like 00:00:23.880 in milliseconds format (1000/25 * 22 = 880).

Frame accuracy is really important : subtitles need to disappear right before the next cut and appear right after the previous one.
Problem is that default HTML5 video's refresh rate is too low: subtitles appear and disappear too late creating a poor viewer's experience (and a non-broadcast compliant one).

Example below higlights the issue. Subtitles in the fixed video disappear right before the change of plan:

It might seem marginal, but the post production industry needs frame accuracy.

Due to browser limitations, timeupdate (event fired when the playing position of a video has changed) is fired every 150-250 milliseconds. It is not enough for frame-accuracy: 25fps means an update every 40ms.
We need to compute which subtitle has to be displayed every frame (instead of doing it every 4-5 frames by default). Video.js subtitles engine does the computation each time the text track's attribute activeCues getter is called.

text-track.js extract from Video.js source code:

Object.defineProperty(tt, 'activeCues', {
    get() {
        if (!this.loaded_) {
            return null;
        }
        // nothing to do
        if (this.cues.length === 0) {
            return activeCues;
        }
        const ct = this.tech_.currentTime();
        const active = [];
        for (let i = 0, l = this.cues.length; i < l; i++) {
            const cue = this.cues[i];

            if (cue.startTime <= ct && cue.endTime >= ct) {
                active.push(cue);
            } else if (cue.startTime === cue.endTime &&
                cue.startTime <= ct &&
                cue.startTime + 0.5 >= ct) {
                active.push(cue);
            }
        }
        changed = false;
        if (active.length !== this.activeCues_.length) {
            changed = true;
        } else {
            for (let i = 0; i < active.length; i++) {
                if (this.activeCues_.indexOf(active[i]) === -1) {
                    changed = true;
                }
            }
        }
        this.activeCues_ = active;
        activeCues.setCues_(this.activeCues_);
        return activeCues;
    },
    set() {}
});

Then you need to call trigger('cuechange') on the text track to make sure the video display is up to date:

player.textTracks()[0].activeCues; // computes the current subtitle based on current time
player.textTracks()[0].trigger('cuechange'); // updates the display

requestAnimationFrame is optimized for animations and has a lot less delay than setInterval or setTimeout, so we are going to use it for our time sensitive loop (Frame rate control source here).

Here is the complete source code:

var fps = 25;
var now;
var then = Date.now();
var interval = 1000/fps;
var delta;

function reloadCues() {
    requestAnimationFrame(reloadCues);

    now = Date.now();
    delta = now - then;

    if (delta > interval) {
        then = now - (delta % interval);

        if(videojs.players.player.textTracks().length == 1) {
            videojs.players.player.textTracks()[0].activeCues;
            videojs.players.player.textTracks()[0].trigger('cuechange')
        }
    }
}
reloadCues();

Demo project is available here.

Originally published on my personal blog.