Labs/Jetpack/Reboot/JEP/107

JEP 107 - Page Mods

Champion: Daniel Buchner - daniel@mozilla.com
Status: Accepted/In-Queue
Bug Ticket:
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

I am not sure, please add to this list if anyone else knows of any

Internal Methods

API Methods

Page Mods Initialization

var myMods = new pageMod({
    'matches': ['*.google.com', 'jetpack.mozillalabs.com'],
    'includes':{
        'script': ['http://ajax.googleapis.com/ajax/libs/mootools/1.2.4/mootools.js'],
        'styles': ['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; }'
    },
    'script': 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:

type - (string) The type of modifier being added. Can be 'matches', 'includes', 'styles', or 'script'. If the only argument passed in is an object, Page Mods assumes multiple modifiers will be passed in.
data -
- matches: (array) an array of web site resource strings
- includes: (object) 'script' or 'style' keyed nodes whose values are arrays of asset resource strings
- styles: (object) an object whose keys are CSS selectors and whose values are objects composed of CSS property keys and values
- script: (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('matches', ['*.digg.com']);

myMods.add('includes', { 
    'script': ['http://ajax.googleapis.com/ajax/libs/mootools/1.2.4/mootools.js'],
    'styles': ['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 initialized a pageMod!');
     }

// Pass in a function reference or a function wrapped block of script.
// Using a function reference enables removal of the script later
// - see the <i>remove</i> method below for more info.

    myMods.add('script', pageLog);

Page Mods Method: remove

Arguments:

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.
data -
- matches: (array) an array of web site resource strings
- includes: (object) 'script' or 'style' 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: (object) expects object nodes keyed with CSS selector strings, whose values are arrays of the CSS property strings you would like to remove
- script: (function reference) removes the script associated with a function reference

Returns:

The attached Page Mods instance

Notes:

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

Examples:

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

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

myMods.remove('styles', {
    'body':['background', 'font-family'],
    'span.details':['font-size']
});

myMods.remove('script', pageLog);

Page Mods Method: empty

Arguments:

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 attached 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');