Confirmed users
162
edits
User:Asqueella/JEP 107: Difference between revisions
Jump to navigation
Jump to search
m
→Script Mods
mNo edit summary |
m (→Script Mods) |
||
| Line 14: | Line 14: | ||
== API == | == API == | ||
=== Script Mods === | === Script Mods === | ||
Here's an example of how the ScriptMod API can be used in a jetpack: | |||
<pre class="brush:js;"> | <pre class="brush:js;"> | ||
var ScriptMod = require("script-mod").ScriptMod; | var ScriptMod = require("script-mod").ScriptMod; | ||
| Line 34: | Line 36: | ||
}); | }); | ||
</pre> | </pre> | ||
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: | |||
* running a script when the page's DOM is ready (<code>ScriptMod.onDOMContentLoaded(''callback'')</code>) | |||
* '''TBD:''' inserting <script> and <link> tags | |||
==== <code>ScriptMod</code> constructor ==== | |||
The <code>ScriptMod</code> constructor takes a single <code>options</code> parameter which is an object that may define the following properties: | |||
* <code>include</code>: an optional parameter, specifying the pages the scripts in this ScriptMod should run on. | |||
** Default behavior is to run the mod's scripts on all pages. | |||
** Providing a string value <code>str</code> is equivalent to providing a single-item array <code>[str]</code>. | |||
** The mod's scripts run on pages, matching ''any'' of <code>include</code> rules. | |||
** Each <code>include</code> rule is a string using one of the following formats (see discussion below): | |||
**# <code>*</code> (a single asterisk) - any page | |||
**# <code>*.domain.name</code> - pages from the specified domain and all its subdomains, regardless of their scheme. | |||
**# <code><nowiki>http://example.com/*</nowiki></code> - any URLs with the specified prefix. | |||
**# <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>. | |||
* <code>script</code>: | |||
===== '''ISSUE:''' What format should be chosen for <code>include</code> rules? ===== | |||
First, a short survey of existing formats: | |||
* [http://wiki.greasespot.net/Include_and_exclude_rules Greasemonkey scripts] specify include and exclude URLs, each may contain wildcards ("*") in any location and may use a special ".tld" domain. These rules get compiled to a regular expression (see [http://github.com/greasemonkey/greasemonkey/blob/master/content/convert2RegExp.js convert2RegExp]), which is then matched against every URL loaded in the browser. | |||
* When specifying CSS styling [https://developer.mozilla.org/en/Using_the_Stylesheet_Service Using the Stylesheet Service], which is an easy and robust way to apply CSS to all content and is also what Stylish uses, you have to describe the filters using CSS, i.e. [https://developer.mozilla.org/index.php?title=En/CSS/%40-moz-document @-moz-document] rule. It allows to specify domain, exact URL, or the URL prefix. | |||
I claim the requirements for the include rules format are: | |||
# Easy to use for the common case (unfortunately, no stats on which cases are common were collected, so we'll guess). | |||
# An efficient implementation that determines which script mods to run on a page should be possible, since there may be many mods installed and each navigation requires us to determine which page mods apply to the page. | |||
# If possible, the <code>include</code> rules for the script and style mods should use the same format. | |||
A non-requirement is high level of control over which URLs are matched, since the highest level of control can be provided via a <code>filter</code> function, but it's important for performance to narrow down the set of URLs before running possibly expensive test determining whether to run the mod on a given page. | |||
<nowiki>#3</nowiki> suggests we use a format that can be transformed to <code>@-moz-document</code> rules, i.e. a format that allows to specify the exact URL, the URL prefix, or the domain. This format also can be efficiently implemented (unlike e.g. a format that allows wildcards in the random positions of the URL). | |||
This is how I've arrived at the format described above. | |||
==== <code>ScriptMod</code> APIs ==== | |||
=== Style mods === | === Style mods === | ||