User:Asqueella/JEP 107: Difference between revisions

Jump to navigation Jump to search

User:Asqueella/JEP 107 (view source)

Revision as of 22:29, 11 April 2010

325 bytes removed ,  11 April 2010
update for Myk's comments <http://groups.google.com/group/mozilla-labs-jetpack/msg/decd886a1ae37018>, except for "include" syntax
(update for Myk's comments <http://groups.google.com/group/mozilla-labs-jetpack/msg/decd886a1ae37018>, except for "include" syntax)
Line 13: Line 13:
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.
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.
This proposal focuses on the JavaScript-based approach.


=== Script Mods ===
=== Script Mods ===
Line 19: Line 19:


<pre class="brush:js;">
<pre class="brush:js;">
var ScriptMod = require("script-mod").ScriptMod;
var ScriptMod = require("page-mod").ScriptMod;
var myMod = new ScriptMod({
var myMod = new ScriptMod({
   include: ["*.example.com",
   include: ["*.example.com",
             "http://example.org/a/specific/url",
             "http://example.org/a/specific/url",
             "http://example.info/*"],
             "http://example.info/*"],
   script: [
   onWindowCreate: function(wrappedWindow) {
    function(wrappedWindow) {
    // this runs each time a new content document starts loading, but
      // this runs each time a new content document starts loading, but
    // before the page starts loading, so we can't interact with the
      // before the page starts loading, so we can't interact with the
    // page's DOM here yet.
      // page's DOM here yet.
    wrappedWindow.wrappedJSObject.newExposedProperty = 1;
      wrappedWindow.wrappedJSObject.newExposedProperty = 1;
  },
    },
  onDOMReady: function(wrappedWindow) {
    ScriptMod.onDOMContentLoaded(function(wrappedWindow) {
    // at this point we can work with the DOM
      // at this point we can work with the DOM
    wrappedWindow.document.body.innerHTML = "<h1>Jetpack Page Mods</h1>";
      wrappedWindow.document.body.innerHTML = "<h1>Jetpack Page Mods</h1>";
  }
    })
  ]
});
});
</pre>
</pre>
Line 41: Line 39:
In this proposal, a script mod specifies the pages it might modify, and the scripts to run on these pages.
In this proposal, a script mod specifies the pages it might modify, and the scripts to run on these pages.


By default, the provided callback function gets called at the earliest possible moment (before the page even started loading, which is made possible by the notifications added in {{bug|549539}}), but there are helpers provided to do common tasks, such as:
The <code>onWindowCreate</code> callback function gets called at the earliest possible moment (before the page even started loading, which is made possible by the notifications added in {{bug|549539}}).
* running a script when the page's DOM is ready (<code>ScriptMod.onDOMContentLoaded(''callback'')</code>)
 
* '''TBD:''' inserting <script> and <link> tags
The <code>onDOMReady</code> callback is called as soon as the page's DOM is ready (on the [http://wiki.greasespot.net/DOMContentLoaded <code>DOMContentLoaded</code>] event)


==== Dependencies ====
==== Dependencies ====
Line 61: Line 59:
**# <code><nowiki>http://example.com/test</nowiki></code> - the single specified URL
**# <code><nowiki>http://example.com/test</nowiki></code> - the single specified URL
* '''TBD:''' <code>filter</code> function instead of (or in addition) to <code>exclude</code>.
* '''TBD:''' <code>filter</code> function instead of (or in addition) to <code>exclude</code>.
* <code>script</code>: an optional parameter specifying the code to run on the matched pages.
* <code>onWindowCreate</code>, <code>onDOMReady</code>: optional parameters specifying the code to run on the matched pages.
** No code is run if this parameter is not specified.
** No code is run if these parameters are not specified.
** Providing a single function <code>func</code> is equivalent to providing a single-item array <code>[func]</code>
** Providing a single function <code>func</code> is equivalent to providing a single-item array <code>[func]</code>
** When the provided value is an array, its items are expected to be functions. Non-function values are ignored.
** When the provided value is an array, its items are expected to be functions. Non-function values are ignored.
** The specified functions are called in order when a page matching the <code>include</code> rules starts to load (but before any content is loaded in the page -- i.e. when the <code>content-document-global-created</code> notification implemented in {{bug|549539}} is issued). An exception thrown from one of the functions does not stop the rest of functions from executing.
** The specified functions are called in order:
*** for <code>onWindowCreate</code> - when a page matching the <code>include</code> rules starts to load (but before any content is loaded in the page -- i.e. when the <code>content-document-global-created</code> notification implemented in {{bug|549539}} is issued)
*** for <code>onDOMReady</code> - when a <code>DOMContentLoaded</code> event fires for the matching page.
** An exception thrown from one of the functions does not stop the rest of functions from executing.
** The specified callbacks are called with a single <code>wrappedWindow</code> parameter -- the content's <code>window</code> object wrapped in an XPCNativeWrapper. The callback's <code>this</code> is the page mod object ('''TBD''' not currently implemented). It goes without saying that with this syntax the callbacks are run in the calling module's scope, not in the content page's scope.
** The specified callbacks are called with a single <code>wrappedWindow</code> parameter -- the content's <code>window</code> object wrapped in an XPCNativeWrapper. The callback's <code>this</code> is the page mod object ('''TBD''' not currently implemented). It goes without saying that with this syntax the callbacks are run in the calling module's scope, not in the content page's scope.


Line 97: Line 98:
** <code id="scriptMod-enable">scriptMod.enable()</code>. Enabling a script mod makes it take effect on any matching pages that start to load after the script mod is enabled. Enabling a script mod does not apply it to existing matching pages.
** <code id="scriptMod-enable">scriptMod.enable()</code>. Enabling a script mod makes it take effect on any matching pages that start to load after the script mod is enabled. Enabling a script mod does not apply it to existing matching pages.
** ''<code>add/remove/empty</code> from the [[Labs/Jetpack/Reboot/JEP/107|original proposal]] appear inessential, especially if the changes are not applied instantly, as in this proposal.''
** ''<code>add/remove/empty</code> from the [[Labs/Jetpack/Reboot/JEP/107|original proposal]] appear inessential, especially if the changes are not applied instantly, as in this proposal.''
* Helper functions available as properties on the <code>ScriptMod</code> constructor
* Helper functions available as properties on the <code>ScriptMod</code> constructor.
** <code>ScriptMod.onDOMContentLoaded(''callback'')</code> - when passed as one of the <code>scripts</code> in the <code>ScriptMod</code> constructor options, calls the <code>callback</code> on matching pages when their DOM is available (on the [http://wiki.greasespot.net/DOMContentLoaded <code>DOMContentLoaded</code>] event).
** TBD other helpers (insert <style>s, <script>s, etc.)
** TBD other helpers (insert <style>s, <script>s, etc.)


=== Style mods ===
=== Style mods ===
TBD
TBD
Asqueella
Confirmed users
162

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/214898"

Navigation menu