Greasemonkey Manual:Environment: Difference between revisions
From GreaseSpot Wiki
Jump to navigationJump to search
m →Control Flow: More table squishing |
m Update for 4.0 |
||
| (17 intermediate revisions by 7 users not shown) | |||
| Line 1: | Line 1: | ||
__NOTOC__ | |||
{{Greasemonkey Manual TOC}} | {{Greasemonkey Manual TOC}} | ||
<div style="border: 3px dotted; color: red; font-size: 1.2em; padding: 0.5em; margin: 1em; text-align: center"> | |||
Warning: This page is out of date and does not accurately describe Greasemonkey 4.0. | |||
</div> | |||
== Why a Special Environment? == | == Why a Special Environment? == | ||
| Line 6: | Line 11: | ||
[[Greasemonkey]] takes advantage of a Firefox feature called [[XPCNativeWrappers]] to insulate the [[user script]] from the content web page, which it references. | [[Greasemonkey]] takes advantage of a Firefox feature called [[XPCNativeWrappers]] to insulate the [[user script]] from the content web page, which it references. | ||
Although this makes it more difficult, or impossible, to do certain things in | Although this makes it more difficult, or impossible, to do certain things in a script, it is a necessary evil. | ||
Earlier [[version history|versions]] of [[Greasemonkey]] had no such sandbox, and as a result, [[security]] holes were uncovered. | Earlier [[version history|versions]] of [[Greasemonkey]] had no such sandbox, and as a result, [[security]] holes were uncovered. | ||
[[Greasemonkey]] provides certain enhanced [[Greasemonkey Manual:APIs|APIs]] to the [[user script]], so that it may accomplish things that a regular web page's | [[Greasemonkey]] provides certain enhanced [[Greasemonkey Manual:APIs|APIs]] to the [[user script]], so that it may accomplish things that a regular web page's JavaScript cannot. | ||
This useful feature has enabled some of the most popular scripts. | This useful feature has enabled some of the most popular scripts. | ||
Unfortunately, when abused, these powerful features can create serious problems. | Unfortunately, when abused, these powerful features can create serious problems. | ||
| Line 15: | Line 20: | ||
Luckily, for almost all the difficulties that the sandbox environment provides, there are ways to still accomplish the desired goal. | Luckily, for almost all the difficulties that the sandbox environment provides, there are ways to still accomplish the desired goal. | ||
The article [ | The article [[Avoid Common Pitfalls in Greasemonkey]] does a wonderful job explaining what the most common snags are, and for each one explains the way to work around the problem. | ||
It is essential reading for any script author. | It is essential reading for any script author. | ||
| Line 22: | Line 27: | ||
This is the raw, un-sandboxed "window" of the content page. | This is the raw, un-sandboxed "window" of the content page. | ||
Certain limited tasks can only be accomplished by referencing this raw window directly, but be warned! | Certain limited tasks can only be accomplished by referencing this raw window directly, but be warned! | ||
JavaScript is a complicated and intricate language, even the most basic operations can be redefined by the content page to perform other actions. | |||
The sandbox environment is provided for | The sandbox environment is provided for the safety of any user of a script. | ||
If at all possible, use of [[unsafeWindow]] should be avoided. | If at all possible, use of [[unsafeWindow]] should be avoided. | ||
== What's Missing? == | == What's Missing? == | ||
Depending on | Depending on the usage, the special [[Greasemonkey]] environment may seem perfectly normal, or excessively limiting. | ||
The Greasemonkey environment is a vanilla [[XPCNativeWrapper]] of the content window, with only certain extra bits added in to emulate a normal environment, or changed. Specifically: | The Greasemonkey environment is a vanilla [[XPCNativeWrapper]] of the content window, with only certain extra bits added in to emulate a normal environment, or changed. Specifically: | ||
:* <code>window</code> is an [[XPCNativeWrapper|XPCNativeWrapper]] of the content window. | :* <code>window</code> is an [[XPCNativeWrapper|XPCNativeWrapper]] of the content window. | ||
:* <code>document</code> is the document object of the XPCNativeWrapper window object. | :* <code>document</code> is the document object of the XPCNativeWrapper window object. | ||
:* [[XPathResult]] is added so that <code>document.evaluate()</code> works. | :* [[XPathResult]] is added so that <code>document.evaluate()</code> works. | ||
:* Unless the [[ | :* Unless the [[Metadata Block#.40unwrap|@unwrap]] metadata imperative is present in the user script header, the entire script is wrapped inside an [http://en.wikipedia.org/wiki/Anonymous_function anonymous function], to guarantee the script's identifiers do not collide with identifiers present in the Mozilla JavaScript sandbox. This function wrapper captures any function definitions and <code>var</code> variable declarations made (e.g. <code>var i = 5;</code>) into the function's local scope. Declarations made without <code>var</code> will however end up on the script's <code>this</code> object, which in Greasemonkey is the global object, contrary to in the normal browser object model, where the <code>window</code> object fills this function. In effect, after <code>i = 5;</code>, the values of <code>window['i']</code> and <code>window.i</code> remain undefined, whereas <code>this['i']</code> and <code>this.i</code> will be 5. See also: [[Global object]] | ||
:* In order to access variables on the page, | :* In order to access variables on the page, use the [[unsafeWindow]] object. To use values defined in a script, simply reference them by their names. | ||
Since Mozilla provides a rich environment, there are a wide variety of things that have ''not'' been imported from the general content scope into the Greasemonkey sandbox. | Since Mozilla provides a rich environment, there are a wide variety of things that have ''not'' been imported from the general content scope into the Greasemonkey sandbox. | ||
Including, but not limited to: | Including, but not limited to: | ||
:* [ | :* [https://developer.mozilla.org/en/DOM/document.createTreeWalker document.createTreeWalker] | ||
:* [http://www.xulplanet.com/references/objref/SOAPCall.html SOAPCall] | :* [http://www.xulplanet.com/references/objref/SOAPCall.html SOAPCall] | ||
Latest revision as of 16:18, 3 November 2017
 Greasemonkey Manual |
| Using Greasemonkey |
|---|
| Installing Scripts |
| Monkey Menu |
| Getting Help |
| User Script Authoring |
| Editing |
| Environment |
| API |
Warning: This page is out of date and does not accurately describe Greasemonkey 4.0.
Why a Special Environment?
When Greasemonkey executes a user script it does so in a special sandbox environment. Greasemonkey takes advantage of a Firefox feature called XPCNativeWrappers to insulate the user script from the content web page, which it references.
Although this makes it more difficult, or impossible, to do certain things in a script, it is a necessary evil. Earlier versions of Greasemonkey had no such sandbox, and as a result, security holes were uncovered.
Greasemonkey provides certain enhanced APIs to the user script, so that it may accomplish things that a regular web page's JavaScript cannot. This useful feature has enabled some of the most popular scripts. Unfortunately, when abused, these powerful features can create serious problems. No exploits were ever uncovered in the wild, but the potential was too great, so the sandbox environment was created.
Luckily, for almost all the difficulties that the sandbox environment provides, there are ways to still accomplish the desired goal. The article Avoid Common Pitfalls in Greasemonkey does a wonderful job explaining what the most common snags are, and for each one explains the way to work around the problem. It is essential reading for any script author.
Finally, of note is the unsafeWindow object present in the sandbox. As the name implies, use of this object is unsafe! This is the raw, un-sandboxed "window" of the content page. Certain limited tasks can only be accomplished by referencing this raw window directly, but be warned! JavaScript is a complicated and intricate language, even the most basic operations can be redefined by the content page to perform other actions. The sandbox environment is provided for the safety of any user of a script. If at all possible, use of unsafeWindow should be avoided.
What's Missing?
Depending on the usage, the special Greasemonkey environment may seem perfectly normal, or excessively limiting.
The Greasemonkey environment is a vanilla XPCNativeWrapper of the content window, with only certain extra bits added in to emulate a normal environment, or changed. Specifically:
windowis an XPCNativeWrapper of the content window.documentis the document object of the XPCNativeWrapper window object.- XPathResult is added so that
document.evaluate()works. - Unless the @unwrap metadata imperative is present in the user script header, the entire script is wrapped inside an anonymous function, to guarantee the script's identifiers do not collide with identifiers present in the Mozilla JavaScript sandbox. This function wrapper captures any function definitions and
varvariable declarations made (e.g.var i = 5;) into the function's local scope. Declarations made withoutvarwill however end up on the script'sthisobject, which in Greasemonkey is the global object, contrary to in the normal browser object model, where thewindowobject fills this function. In effect, afteri = 5;, the values ofwindow['i']andwindow.iremain undefined, whereasthis['i']andthis.iwill be 5. See also: Global object - In order to access variables on the page, use the unsafeWindow object. To use values defined in a script, simply reference them by their names.
Since Mozilla provides a rich environment, there are a wide variety of things that have not been imported from the general content scope into the Greasemonkey sandbox. Including, but not limited to:
The more esoteric the method, the less likely that it has been included in the Greasemonkey sandbox.
See also
- Wikipedia: Sandbox
- Security
- Avoid Common Pitfalls in Greasemonkey
