Labs/Jetpack/Reboot/JEP/108: Difference between revisions

From MozillaWiki
< Labs‎ | Jetpack‎ | Reboot‎ | JEP
Jump to navigation Jump to search
Line 40: Line 40:


#<b>options</b> - (<i>object</i>)
#<b>options</b> - (<i>object</i>)
#* matches: (<i>array</i>) an array of web site resource strings
#* bind: (<i>mixed</i>) a variable that will be bound as the 'this' keyword in the function
#* includes: (<i>object</i>) 'script' or 'style' keyed nodes whose values are arrays of asset resource strings
#* arguments: (<i>array > mixed</i>) an array of mixed variables passed as the function arguments
#* styles: (<i>object</i>) an object whose keys are CSS selectors and whose values are objects composed of CSS property keys and values
#* timeout: (<i>number</i>) a number that is used to set the timeout duration
#* script: (<i>function</i>) a function that will be injected into the page and called. By default, the function is bound with the target document's window object
#* interval: (<i>number</i>) a number that is used to set the interval duration
#<b>executable</b> - (<i>array</i>) an array of web site resource strings
#<b>action</b> - (<i>function</i>) a function to be executed within the DOM of the Background Page - by default, the Background Page's window object is the bound 'this' within the function


<b>Returns:</b>
<b>Returns:</b>


The Page Mods instance
<b>user defined return value</b> - The function's return value as specified by the user
 
or
 
<i>If timeout or interval options are used:</i>
 
<b>array</b> - an array whose first item is the function's user defined return value, and second is a variable the user can save to clear the timing event


<b>Notes:</b>
<b>Notes:</b>


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.


<b>Examples:</b>
<b>Examples:</b>

Revision as of 22:03, 5 February 2010

JEP 108 - Background Page

  • Champion: Daniel Buchner - daniel@mozilla.com
  • Status: Accepted/In-Queue
  • Bug Ticket:
  • Type: API


Proposal

Background Pages are like a more open and free sandbox for doing most anything in a traditional web page with a DOM context, but with a key difference: the page is augmented with escalated, waterfall chrome privileges. It is essentially along the same line of a Web Worker, just more open and accessible.

Key Issues

Dependencies & Requirements

  • We must be able to give the code in the top window of this page chrome privileges that are strictly one-way/descending in nature.
  • Dynamically generated code sent to the Background Page should be injected and executed in the Background Page's window context.


Internal Methods

  • TBD

API Methods

$dom.run({ interval: 10000, bind:$tabs.get('index', 0) }, function(){
    return window.location;
});
  • Background Page work units are bound with the Background Page's window object by default
  • If interval option is present, the function is wrapped with setInterval(); and the $Moz.background method returns the interval timer so that it may be cleared outside of the Background Page.
  • Functional context for the function passed to the background page can be passed as an option

Background Page Global: $dom

Background Page Method: run

Arguments:

  1. options - (object)
    • bind: (mixed) a variable that will be bound as the 'this' keyword in the function
    • arguments: (array > mixed) an array of mixed variables passed as the function arguments
    • timeout: (number) a number that is used to set the timeout duration
    • interval: (number) a number that is used to set the interval duration
  2. action - (function) a function to be executed within the DOM of the Background Page - by default, the Background Page's window object is the bound 'this' within the function

Returns:

user defined return value - The function's return value as specified by the user

or

If timeout or interval options are used:

array - an array whose first item is the function's user defined return value, and second is a variable the user can save to clear the timing event

Notes:


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 logged a message with Page Mods!');
}

// 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:

  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.
  2. 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) removes the script associated with a function reference

Returns:

The 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:

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