The location hack is an ugly but useful way to interact with the content scope of the page being user scripted.
For security reasons, Greasemonkey uses XPCNativeWrappers and sandbox to isolate it from the web page. Under this system, the user script can access and manipulate the page using event listeners, the DOM API, and GM_* functions.
Sometimes the sandbox is too limiting, in which case the user script can access other parts of the page using unsafeWindow. As the name unsafeWindow implies, this can often be unsafe, and expose security holes.
In December 2005, Jesse Ruderman came up with the location hack, to be an alternative to unsafeWindow in many cases.
Basic usage: page functions
Suppose the page contains a function called
window.pageFunc. The user script knows this function as
The user script could simply call
Similarly, a user script can set location.href to this URL to safely call the function:
Invoke onclick behavior
Sometimes a userscript wants to simulate the behavior of clicking a link that has an onclick handler. For example on YouTube video pages in the video description there is the link more with an onclick handler that as of this writing can be found with the XPath
"//div[@id='videoDetailsDiv']//a[text() = 'more']/@onclick"
and it contains
addClass(_gel('videoDetailsDiv'), 'expanded'); return false;
If the variable
onclick is bound to the XPath result, then this handler can be invoked through location thusly:
Note that the onclick has to be wrapped in a function so that its
return has a scope and the whole needs to be wrapped in
This example is rather robust because it will still work if YouTube redefines the content of its onclicks.
This hack can also be used to trigger
location.href = someLink.href;
Modifying the page
The location hack can do anything a page script or bookmarklet can do, so it can modify content variables and such as easily as it can access them. For example:
Executing large blocks of code
Even though the function is defined in the sandbox, it is not a closure of the sandbox scope. It is converted to a string and then back to a function in page scope. It cannot access anything in the sandbox scope, which is a limitation, but is also essential to making this technique secure.
Percent encoding issue
Sometimes percent-encoding the percent symbol is required. For example,
The above code will cause error because %22 is interpreted as double quotation mark. The workaround is:
See also encodeURI().
Functions called through the location hack cannot return data directly to the user script scope. To communicate between location hack code and regular user script code, data must be placed where the user script can see it, for example, by writing it into the DOM, or by triggering an event. A simple example:
Function to get values of global variables
The following function can be used to access the values of global variables using
var value = GM_getGlobalElement('globalVariable');. Please note that the returned value is converted to a string.