User:Asqueella/JEP 107

This is an edited version of Labs/Jetpack/Reboot/JEP/107.

Page Mods

There are two common ways to modify web pages from the browser:

• by specifying custom CSS to apply to specific pages, sites, or all web content. (This is what Stylish extension does.)
• by letting specified scripts run modify the web page (see Greasemonkey extension)

The CSS-only approach is less powerful, yet often simpler and allows to dynamically apply and cancel custom style modifications to the page.

The JavaScript-based approach allows virtually any changes to the page to be implemented, but requires special (and non-trivial) effort to implement instant application and undoing of these modifications.

ISSUE: Therefore, it might make sense to provide separate APIs for these two types of modifications. We'll call them "Script mods" and "Style mods" below.

Script Mods

var ScriptMod = require("script-mod").ScriptMod;
var myMod = new ScriptMod({
  include: ["*.example.com",
            "http://example.org/a/specific/url",
            "http://example.info/*"],
  script: [
    function(wrappedWindow) {
      // this runs each time a new content document starts loading, but
      // before the page starts loading, so we can't interact with the
      // page's DOM here yet.
      wrappedWindow.wrappedJSObject.newExposedProperty = 1;
    },
    ScriptMod.onDOMContentLoaded(function(wrappedWindow) {
      // at this point we can work with the DOM
      wrappedWindow.document.body.innerHTML = "<h1>Jetpack Page Mods</h1>";
    })
  ]
});

Use Cases

1. Creation of CSS-based add-ons like Stylish, EditCSS, etc...
2. Creation of JS-based add-ons like Execute JS, JS Exec etc...
3. In General: Any Greasemonky-style add-on, with the advantage that this API would allow for far greater flexibility - turning on and off only certain parts of a mod, automatically flashing a new url/web-page with the active parts of a mod by using the add method to include a new match to the matches white-list

Common Actions

The API, if done in this fashion, give the developer the ability to dramatically simplify application actions such as:

• Creating an instance of Page Mods that adds script or styles to a set of matched urls
• Further extending and existing instance of Page Mods with additional styles and script
• Toggling on and off specific styles or script within a Page Mods instance
• Adding new matches to a Page Mods instance, which in turn instantly applies active styles and script within that instance to the newly added matches.
• Multiple instances of Page Mods can be instantiated, which enables a whole cadre of functionality that the object-bound 'singleton' implementation neglects.