Labs/Jetpack/Reboot/JEP/107

JEP 107 - Page Mods

• Champion: Daniel Buchner - daniel@mozilla.com
• Status: Accepted/Pre-Production
• Bug Ticket: 546739
• Type: API
• Difficulty: 4

Proposal

Page Mods is chiefly aimed at modifying and manipulating content documents within Firefox. Pages Mods should perform this functionality in a seamless fashion where the end result is the only change visible to the user.

Key Issues

When documents load that are represented in the "matches" white-list, we must ensure that script and styles injected into the page are evaluated by the parser in the normal load cycle. Perhaps we achieve this by dynamically creating resource (or custom protocol) URIs that contain the style and script blocks entered similar to the Background Page mechanisms. These URIs would be dynamically created CSS/JS files that would then be injected in the appropriate places withing the matched documents (CSS files in the doc head, JS files just after the close of the body tag).

Dependencies & Requirements

• Requires JEP 104 - Simple Storage
• Ability to dynamically create a resource, such a method would require JEP 106 - Registered Jetpack URLs
• Capturing the page pre-render and injecting resources, for example: linked style sheets in the header and script tags after the body
• Ability to access extension specific resources

API Methods

Page Mods Initialization

var myMods = new pageMod({
  'includes': ['*.google.com', 'jetpack.mozillalabs.com'],
  'excludes': ['https://mail.google.com/*'],
  'files': {
      'javascript': ['http://ajax.googleapis.com/ajax/libs/mootools/1.2.4/mootools.js'],
      'stylesheet': ['http://yui.yahooapis.com/3.0.0/build/cssbase/base-min.css']
  },
  'styles': [
    'body { background: #ffffff; font-family: Trebuchet MS; }',
    'span.details { font-size: 7px; }'
  ],
  'scripts': [function(){
      $('container').addEvents({
          'click:relay(ul li)': function(){ this.setStyles('background','#000') },
          'mousenter:relay(ul li)': function(){ this.tween('background','#000') },
          'mouseleave:relay(ul li)': function(){ this.tween('background','#fff') }
      });
    }
  ]
});

Page Mods Method: add

Arguments:

1. type - (string) The type of modifier being added. Can be 'includes', 'excludes', 'files', 'styles', or 'scripts'. If the only argument passed in is an object, Page Mods assumes multiple modifiers will be passed in.
2. data -
   • includes: (array) an array of URL strings to apply mods to
   • excludes: (array) an array of URL strings to skip when modding
   • files: (object) 'javascript' or 'stylesheet' keyed nodes whose values are arrays of asset resource strings
   • styles: (array) an array of styles, wherein each array item is a selector and contained within are properties and values.
   • scripts: (function) a function that will be injected into the page and called. By default, the function is bound with the target document's window object

Returns:

The Page Mods instance

Notes:

Modifications passed to the Page Mods instance with this method will be added, and persist, on open and future documents matching all of the URL(s) currently on the 'matches' white-list.

Examples:

myMods.add('includes', ['*.digg.com']);

myMods.add('excludes', ['http://labs.digg.com/*']);

myMods.add('files', { 
  'javascript': ['http://ajax.googleapis.com/ajax/libs/mootools/1.2.4/mootools.js'],
  'stylesheet': ['http://yui.yahooapis.com/3.0.0/build/cssbase/base-min.css']
});

myMods.add('styles', ['body: { background: #ffffff; font-family: Trebuchet MS; }', 'span.details { font-size: 7px; }']);

// Creating a function reference

var pageLog = function(){
  console.log('I just logged a message with Page Mods!');
}

// Using a function reference enables removal of the script later, see
// the remove method below for more info.

myMods.add('scripts', pageLog);

Page Mods Method: remove

Arguments:

1. type - (string) The type of modifier being added. Can be 'includes', 'excludes', 'files', 'styles', or 'script'. NOTE: If the only argument is an object, Page Mods assumes multiple modifiers will be passed in.
2. data -
   • includes: (array) an array of URL strings (removal reloads modded docs)
   • excludes: (array) an array of URL strings (removal applies mods to docs if any are open)
   • files: (object) 'javascript' or 'stylesheet' keyed nodes whose values are arrays of asset resource strings. Passing string of 'all' for the value of either 'include' key of 'styles' or 'script' will remove all includes of that type.
   • styles: (array) an array of styles, wherein each array item can be a selector name only (to remove all styles related to the selector) or additionally, can include specific property names (removing only styles of that property while leaving unmentioned selector styles intact).
   • scripts: (function) removes the script associated with a function reference

Returns:

The Page Mods instance

Notes:

NEEDS FEEDBACK: Removal of any 'includes', 'excludes', 'scripts', or 'files' of the keyed node-type 'javascript' will prompt the user asking whether or not to reload for any documents that contain, or are affected by, the modification's removal.

Examples:

myMods.remove('includes', ['*.google.com']);

myMods.remove('excludes', ['http://labs.digg.com/*']);

myMods.remove('files', {
  'javascript': 'all',
  'stylesheet': ['http://yui.yahooapis.com/3.0.0/build/cssbase/base-min.css']
});

myMods.remove('styles', [
  'body { background; font-family; }',
  'span.details'  //This would remove all styles for the selector
]);

myMods.remove('script', pageLog);

Page Mods Method: empty

Arguments:

1. type - (string) The type of modifier being added. Can be 'matches', 'includes', 'styles', or 'script'. NOTE: If the only argument is an object, Page Mods assumes multiple modifiers will be passed in.

Returns:

The Page Mods instance

Notes:

NEEDS FEEDBACK: Emptying of 'matches', 'script', or 'includes' will reload any documents that contain, or are affected by, the modification's removal.

Examples:

myMods.empty('includes');

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.