|
|
| (17 intermediate revisions by one other user not shown) |
| Line 1: |
Line 1: |
| == JEP 108 - Background Page == | | == JEP 108 - Page Worker == |
|
| |
|
| * Champion: Daniel Buchner - daniel@mozilla.com | | * Champion: Daniel Buchner - daniel@mozilla.com |
| * Status: Accepted/In-Queue | | * Status: Under Review |
| * Bug Ticket: | | * Bug: [https://bugzilla.mozilla.org/show_bug.cgi?id=546740 546740] |
| * Type: API | | * Type: API |
|
| |
|
|
| |
|
| === Proposal === | | === 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.
| | Page Worker is like a more open 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 === | | === Use-Cases === |
| | 1. Google Maps API Data |
| | If you wanted to utilize the data available via Google Maps API, you would need to instantiate the API's script within the context of a DOM. This is due to Google Maps reliance on the elements and script it pulls in to make data fetching possible. I might want to have a Jetpack that searches the page for addresses and business titles allowing the user to mouseover those items and view geolocalized details about such places in a tooltip. |
| | |
| | 2. Native Type Proxy & DOM-Reliant Script Execution Environment |
| | It is almost a certainty that developers will want to use their js library of choice to interact with web content. To enable this more easily, they could use this JEP's DOM as a Native Type proxy and as the primary location to instantiate their DOM dependent code. |
|
| |
|
| === Dependencies & Requirements === | | === 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. | | * 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. | | * Dynamically generated code sent to the Page Worker should be injected and executed in the Page Worker's window context. |
|
| |
|
|
| |
|
| Line 22: |
Line 27: |
| == API Methods == | | == API Methods == |
|
| |
|
| <pre> | | ==== Page Worker Global: <i>$page</i> ==== |
| $dom.run({ interval: 10000, bind:$tabs.get('index', 0) }, function(){
| |
| return window.location;
| |
| });
| |
| </pre> | |
|
| |
|
| * Background Page work units are bound with the Background Page's window object by default
| | ==== Page Worker Method: <i>run</i> ==== |
| * 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.
| | <b>Description:</b> |
| * Functional context for the function passed to the background page can be passed as an option
| |
|
| |
|
| ==== Page Mods <i>Initialization</i> ====
| | Allows you to run code in the Page Worker's window context. |
|
| |
|
| | <b>Arguments:</b> |
|
| |
|
| <pre class="brush:js;"> | | #<b><i>options</i></b> - (<i>object</i>) |
| var myMods = new pageMod({
| | #* bind: (<i>mixed</i>) a variable that will be bound as the 'this' keyword in the function |
| 'matches': ['*.google.com', 'jetpack.mozillalabs.com'],
| | #* arguments: (<i>array</i>) an array of mixed variables passed as the function arguments |
| 'includes': {
| | #* timeout: (<i>number</i>) a number that is used to set the timeout duration |
| 'script': ['http://ajax.googleapis.com/ajax/libs/mootools/1.2.4/mootools.js'],
| | #* interval: (<i>number</i>) a number that is used to set the interval duration |
| 'styles': ['http://yui.yahooapis.com/3.0.0/build/cssbase/base-min.css']
| | #<b><i>action</i></b> - (<i>function</i>) a function to be executed within the DOM of the Page Worker - by default, the Page Worker's window object is the bound 'this' within the function |
| },
| |
| 'styles': {
| |
| 'body': {
| |
| 'background': '#ffffff',
| |
| 'font-family': 'Trebuchet MS'
| |
| }
| |
| },
| |
| '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') }
| |
| });
| |
| }
| |
| });
| |
| </pre>
| |
|
| |
|
| ==== Page Mods Method: <i>add</i> ====
| | <b>Returns:</b> |
|
| |
|
| <b>Arguments:</b> | | <b><i>user defined return value</i></b> - The function's return value as specified by the user |
|
| |
|
| #<b>type</b> - (<i>string</i>) 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.
| | or |
| #<b>data</b> -
| |
| #* matches: (<i>array</i>) an array of web site resource strings
| |
| #* includes: (<i>object</i>) 'script' or 'style' keyed nodes whose values are arrays of asset resource strings
| |
| #* styles: (<i>object</i>) an object whose keys are CSS selectors and whose values are objects composed of CSS property keys and values
| |
| #* 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
| |
|
| |
|
| <b>Returns:</b> | | <i>If timeout or interval options are used:</i> |
|
| |
|
| The Page Mods instance
| | <b><i>array</i></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> |
|
| |
|
| <pre class="brush:js;"> | | <pre class="brush:js;"> |
| myMods.add('matches', ['*.digg.com']);
| | $page.run({ interval: 10000 }, function(){ |
| | | return window.location; |
| 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']
| |
| }); | | }); |
| | </pre> |
|
| |
|
| myMods.add('styles', {
| | ==== Page Worker Method: <i>empty</i> ==== |
| 'body': {
| | <b>Description:</b> |
| '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
| | Empties the Page Worker's of all elements (this includes the body, which is then reinserted fresh). |
| // the <i>remove</i> method below for more info.
| |
| | |
| myMods.add('script', pageLog);
| |
| </pre>
| |
| | |
| ==== Page Mods Method: <i>remove</i> ====
| |
|
| |
|
| <b>Arguments:</b> | | <b>Arguments:</b> |
|
| |
|
| #<b>type</b> - (<i>string</i>) 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.
| | <i>This method takes no arguments</i> |
| #<b>data</b> -
| |
| #* matches: (<i>array</i>) an array of web site resource strings
| |
| #* includes: (<i>object</i>) '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: (<i>object</i>) expects object nodes keyed with CSS selector strings, whose values are arrays of the CSS property strings you would like to remove
| |
| #* script: (<i>function</i>) removes the script associated with a function reference
| |
|
| |
|
| <b>Returns:</b> | | <b>Returns:</b> |
|
| |
|
| The Page Mods instance | | The Page Worker Global object: <i>$page</i> |
| | |
| <b>Notes:</b> | |
| | |
| 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.
| |
|
| |
|
| <b>Examples:</b> | | <b>Examples:</b> |
|
| |
|
| <pre class="brush:js;"> | | <pre class="brush:js;"> |
| | $page.empty(); |
| | </pre> |
|
| |
|
| myMods.remove('matches', ['*.google.com']);
| | ==== Page Worker Method: <i>reset</i> ==== |
| | | <b>Description:</b> |
| 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);
| |
| | |
| </pre> | |
|
| |
|
| ==== Page Mods Method: <i>empty</i> ====
| | Resets the Page Worker to a blank HTML page with no elements and a clean global window object. |
|
| |
|
| <b>Arguments:</b> | | <b>Arguments:</b> |
|
| |
|
| #<b>type</b> - (<i>string</i>) 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.
| | <i>This method takes no arguments</i> |
|
| |
|
| <b>Returns:</b> | | <b>Returns:</b> |
|
| |
|
| The Page Mods instance | | The Page Worker Global object: <i>$page</i> |
| | |
| <b>Notes:</b> | |
| | |
| NEEDS FEEDBACK: Emptying of 'matches', 'script', or 'includes' will reload any documents that contain, or are affected by, the modification's removal.
| |
|
| |
|
| <b>Examples:</b> | | <b>Examples:</b> |
|
| |
|
| <pre class="brush:js;"> | | <pre class="brush:js;"> |
| myMods.empty('includes');
| | $page.reset(); |
| </pre> | | </pre> |