Include and exclude rules: Difference between revisions
(finish (clicked wrong button earlier!) moving "Scriptable content" page into this) |
|||
| Line 12: | Line 12: | ||
If no include rule is provided, <code>@include *</code> is assumed. That is, every URL will be matched within the allowed [[#Greaseable_schemes |Greaseable schemes]]. | If no include rule is provided, <code>@include *</code> is assumed. That is, every URL will be matched within the allowed [[#Greaseable_schemes |Greaseable schemes]]. | ||
== Greaseable schemes == | == Greaseable schemes == | ||
| Line 37: | Line 35: | ||
In both cases this restriction is intended to prevent security/privacy vulnerabilities. | In both cases this restriction is intended to prevent security/privacy vulnerabilities. | ||
== Magic TLD == | |||
The only special syntax besides the wildcard is .tld. An include such as <code><nowiki>http://www.example.tld/*</nowiki></code> will match any top level domain, such as <code>www.example.com</code>, <code>www.example.org</code>, <code>www.example.co.uk</code>, and so on. One must be careful with this, to not accidentally leak data to a site that they did not mean to match. This list of TLDs includes a myriad of dual-segment TLDs (such as ca.us, aeroport.fr and kyoto.jp), beside the plain country or category codes (com, jp, se). For a full list see the [[Magic TLD]] page. | |||
== Data scheme user scripts == | == Data scheme user scripts == | ||
| Line 43: | Line 45: | ||
For example, the below URI will display a HTML page that indirectly includes an image from google.com as its sole content: | For example, the below URI will display a HTML page that indirectly includes an image from google.com as its sole content: | ||
data:text/html;charset=utf-8,<html><head><title>data: test</title></head><body><img src=' | <nowiki>data:text/html;charset=utf-8,<html><head><title>data: test</title></head><body><img src='http://www.google.com/intl/en_ALL/images/logo.gif'></body></html></pre></nowiki> | ||
[http://tinyurl.com/yl8djvy This link] points to the above data URI and can be clicked to see it in action. | [http://tinyurl.com/yl8djvy This link] points to the above data URI and can be clicked to see it in action. | ||
Firefox ignores unknown | Firefox ignores unknown semicolon separated parameters in the header of a <code>data</code> URI (and the standards seem to leave this possibility open) which means if one adds say the string <code>MyScript;</code> in the header of the above URI, giving: | ||
data:text/html;MyScript;charset=utf-8,<html><head><title>data: test</title>.... | data:text/html;MyScript;charset=utf-8,<html><head><title>data: test</title>.... | ||
| Line 58: | Line 60: | ||
This ability can be useful if a user script creates one or more <code>data</code> URIs and then opens them. Augmenting the URIs with some extra marking can cause specific user scripts to run in their windows. For example, a user script can create a <code>data URI</code> that contains a HTML <code>table</code> and trigger a user script for it that allows the user sort it. | This ability can be useful if a user script creates one or more <code>data</code> URIs and then opens them. Augmenting the URIs with some extra marking can cause specific user scripts to run in their windows. For example, a user script can create a <code>data URI</code> that contains a HTML <code>table</code> and trigger a user script for it that allows the user sort it. | ||
Revision as of 18:54, 3 February 2010
User scripts specify include and exclude rules in the metadata block.
The script will execute if it matches any include rule, as long as it does not match an exclude rule.
The rules are URLs, which can have a "wildcard" asterisk (*), which matches any string including the empty string. For example: http://www.example.com/foo/* will match http://www.example.com/foo/bar and http://www.example.com/foo/, but not http://www.example.com/baz/. A rule can have several wildcards or none, in which case the rule must match the entire URL exactly. Exclude rules look the same, and prevent the script from being executed. An example:
// ==UserScript== // @include http://www.example.com/foo/* // @include http://www.example.org/*.bar // @exclude http://www.example.com/foo/baz // ==/UserScript==
If no include rule is provided, @include * is assumed. That is, every URL will be matched within the allowed Greaseable schemes.
Greaseable schemes
Greasemonkey will run scripts only on documents loaded from particular schemes. By default, those are:
- http
- https
- ftp
- data
(Note: What is officially called a 'scheme' in a URL is also found in Javascript as the .protocol property of any abstract link element such as <a>, <link>, or a DOM object such as document.location.)
Extra schemes
Greasemonkey will also run scripts on:
- file
- Only if
greasemonkey.fileIsGreaseableis set totruein about:config. - about
- Only if
greasemonkey.aboutIsGreaseableis set totruein about:config.
(But about:blank is always allowed.)
In both cases this restriction is intended to prevent security/privacy vulnerabilities.
Magic TLD
The only special syntax besides the wildcard is .tld. An include such as http://www.example.tld/* will match any top level domain, such as www.example.com, www.example.org, www.example.co.uk, and so on. One must be careful with this, to not accidentally leak data to a site that they did not mean to match. This list of TLDs includes a myriad of dual-segment TLDs (such as ca.us, aeroport.fr and kyoto.jp), beside the plain country or category codes (com, jp, se). For a full list see the Magic TLD page.
Data scheme user scripts
Browsers can open windows in which all of the page top content is contained in a data scheme URI. For example, the below URI will display a HTML page that indirectly includes an image from google.com as its sole content:
data:text/html;charset=utf-8,<html><head><title>data: test</title></head><body><img src='http://www.google.com/intl/en_ALL/images/logo.gif'></body></html></pre>
This link points to the above data URI and can be clicked to see it in action.
Firefox ignores unknown semicolon separated parameters in the header of a data URI (and the standards seem to leave this possibility open) which means if one adds say the string MyScript; in the header of the above URI, giving:
data:text/html;MyScript;charset=utf-8,<html><head><title>data: test</title>....
one can then use Include and exclude rules such as
@include data:text/html;MyScript;*
to trigger user scripts to run on a subtype of data URIs.
This ability can be useful if a user script creates one or more data URIs and then opens them. Augmenting the URIs with some extra marking can cause specific user scripts to run in their windows. For example, a user script can create a data URI that contains a HTML table and trigger a user script for it that allows the user sort it.
