User Scripts

marklieberman edited this page Jul 12, 2018 · 13 revisions

User scripts are subject to all of the usual limitations of web extensions. Specifically, the user script is evaluated in the content script environment. Within the content script you will have limited access to web extension APIs.

To access privileged APIs, the user script must execute in the background script environment. Foxy Gestures provides a executeInBackground() function to allow user scripts to execute code in the background.

Available web extension APIs are restricted based on the permissions key in manifest.json so please create an issue if you require access to additional APIs.

User Script Scope

User scripts are evaluated in the content/commands.js module within the frame where the gesture began. Functions passed to executeInBackground() are evaluated in background/commands.js. You may invoke any of the built-in commands in each module in your user script.

The following useful variables are in scope in your user script. These may be changed or renamed as the extension evolves.

  • data: An object containing the serializable event information for the gesture. For example:
data = {
      "mediaSource": "",
      "mediaType": "image/jpg"
  • mouseDown: A reference to the first mousedown event in the gesture.

  • A reference to the DOM element under the mouse when the gesture started.

  • data.element.linkHref is the href attribute of any enclosing <a> tag, not just the href of the element under the gesture..

  • data.element.mediaSource is the src attribute of any media element (img,video,audio,etc.) under the mouse.

  • data.element.mediaType is the mime type of any media element under the mouse. Only populated if specified, such as in HTML5 audio and video elements. It may be used to infer a file type from extensionless source URLs.

Repeatable Wheel and Chord Gestures

By default, a wheel or chord gesture can only be performed once and then the gesture is complete. (This ensures that the gesture state is cleaned up if the active tab changes.) If you want to repeat the gesture without releasing all buttons, you can end your user script like so:

// Allow the wheel or chord gesture to repeat.
var result = { repeat: true };


executeInBackground(func, args);

Executes a function in the privileged background context. func is a function to execute. args is an array of arguments to pass to func. This function works by serializing func using Function.prototype.toString() and sending it to the background context. You may not use any closures or references external to func. All values in args must be serializable as JSON, so you cannot use DOM references. This function returns a promise that is resolved with the return value of func.


var src = data.element.mediaInfo && data.element.mediaInfo.source;
var promise = executeInBackground(src => {
  return{ url: src });
}, [ src ]);

promise.then(downloadId => {
  console.log('download ID is', downloadID);

Useful Functions


Returns a promise that resolves to the currently active window.


Returns a promise that resolves to an array of tabs in the currently active window.


Invokes the callback passing the currently active tab as the only argument.


Open Image In New Tab

var src = data.element.mediaInfo && data.element.mediaInfo.source;
if (src) {
    executeInBackground(src => {
        getActiveTab(tab => browser.tabs.create({
            url: src,
            index: tab.index + 1,
            active: true
    }, [ src ]);

Pattern Matching Quick Save

Saves an image, video, or audio file to custom location in the downloads folder. Rules are evaluated in order to determine the target path and filename.

(function () {
    let src = data.element.mediaInfo && data.element.mediaInfo.source;
    if (!src) {
        setStatus('Quick Save: No media found');
    let placeholders = [], rules = [];
    // -- Define placeholders --
    placeholders.push([ '%IMAGE_DIR%', 'Images/' ]);
    placeholders.push([ '%VIDEO_DIR%', 'Video/' ]);
    placeholders.push([ '%AUDIO_DIR%', 'Audio/' ]);
    // -- Define rules --
    // Capturing group 1 must be the filename.
    // Defaults
    rules.push({ name: 'Images', regex: /([^\/]+\.(gif|png|jpe?g))($|\?|#)/i, target: '%IMAGE_DIR%/%F%', erase: true });
    rules.push({ name: 'Video', regex: /([^\/]+\.(webm|mp4|mkv))($|\?|#)/i, target: '%VIDEO_DIR%/%F%' });
    rules.push({ name: 'Audio', regex: /([^\/]+\.(mp3|flac|m4a|aac))($|\?|#)/i, target: '%AUDIO_DIR%/%F%' });

    // Evaluate rules
    let match = null;
    for (let i = 0; i < rules.length; i++) {
        if ((match = src.match(rules[i].regex)) != null) {
            // Evaluate placeholders
            let filename = match[1];
            placeholders.push([ '%F%', filename ]);
            let target = placeholders.reduce((target, placeholder) => target.replace(placeholder[0], placeholder[1]), rules[i].target);
            // -- Privileged operation begin --
            return executeInBackground((rule, src, target) => { 
                // Start the download
                return{ url: src, filename: target }).then(id => {
                    if (rule.erase) {
                        // Remove the download from history on completion
                        let listener = (downloadDelta) => {
                            if (( === id) && (downloadDelta.state.current !== 'in_progress')) {
                                browser.downloads.erase({ id: });
            }, [ rules[i], src, target ])
            // -- Privileged operation end --
                .then(x => setStatus('Quick Save: Saved "' + filename + '" using ' + rules[i].name))
                .catch(err => setStatus('Quick Save: Failed to save "' + filename + ': ' + err));
    setStatus('Quick Save: No matching rule');
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.