How to access `window` (Target page) objects when @grant values are set?

When you set a @grant value other than none, Greasemonkey activates its sandbox and Greasemonkey 2.0 radically changed unsafeWindow handling.

Now, in order to create or overwrite variables in the target-page scope, you must correctly chose from a menu of techniques. EG:

To Read:

• A simple variable:

  Target page sets:       var foo = "bar";
  GM script can read:     unsafeWindow.foo    //-- "bar"
  

• A simple object:

  Target page sets:       var obj = {A: 1};
  GM script can read:     unsafeWindow.obj    //-- Object { A: 1 }
  

• A complex object: This is not always possible.

To Call:

• A simple function:

  Target page sets:       function func () {console.log ('Hi');}
  GM script can call:     unsafeWindow.func() //-- "Hi"
  

• A complex function: This is not always possible.

To Write/Set:

• A simple variable:

  unsafeWindow.foo = "Apple";
  

• A simple object:

  var gmObject        = {X: "123"};
  unsafeWindow.obj    = cloneInto (gmObject, unsafeWindow);
  

• A simple function:

  function gmFunc () {
      console.log ("Lorem ipsum");
      //-- Can use GM_ functions in here! :)
  }
  unsafeWindow.func   = exportFunction (gmFunc, unsafeWindow);
  

---

Consider this HTML:

<button id="helloBtn">Say "Hello".</button>

And this javascript:

var simpleGlobalVar = "A simple, global var in the page scope.";
var globalObject    = {Letter: "A", Number: 2};

function simpleFunction () {
    console.log ("The target page's simpleFunction was called.");
}

var sayHello = function() {
    console.log ('Hello.');
}

document.getElementById ('helloBtn').addEventListener ('click', function () {
    sayHello ();
} );

which you can see live at this jsFiddle page.

If you install and run this Greasemonkey script against that page:

// ==UserScript==
// @name     _Demonstrate accessing target-page variables with @grant values set
// @include  http://fiddle.jshell.net/sepwL7n6/*/show/
// @require  http://ajax.googleapis.com/ajax/libs/jquery/2.1.0/jquery.min.js
// @grant    GM_addStyle
// ==/UserScript==

console.log ("*** Greasemonkey script start.");

$("body").append ('<div id="gmArea">Added by Greasemonkey:<p></p></div>');
$("#gmArea > p:first").append ('<button id="gmShow">Access select target-page variables and functions</button>');
$("#gmArea > p:first").append ('<button id="gmChange">Change javascript things in the target-page scope.</button>');

$("#gmShow").click ( function () {
    //-- Access things from the target-page scope:
    console.log ("----------------");
    console.log ("==> simpleGlobalVar is: ", unsafeWindow.simpleGlobalVar);
    console.log ("==> globalObject    is: ", unsafeWindow.globalObject);
    console.log ("==> Calling target's simpleFunction():");
    unsafeWindow.simpleFunction ();

    //-- WARNING! This next technique is not robust, but works in some cases.
    console.log ("==> Calling target's button's click().");
    unsafeWindow.document.getElementById ('helloBtn').click ();
} );

$("#gmChange").click ( function () {
    this.disabled = true;   //-- Can only click once.
    unsafeWindow.simpleGlobalVar    = "Simple var... Intercepted by GM!";
    unsafeWindow.globalObject       = cloneInto (gmObject, unsafeWindow);
    unsafeWindow.sayHello           = exportFunction (sayHello, unsafeWindow);
    console.log ("==> Target page objects were changed.");
} );

var gmMessageStr    = "Function... Intercepted by GM, but also can use GM_ functions!";
function sayHello () {
    sayHello.K      = (sayHello.K  ||  0) + 1;
    console.log (gmMessageStr);
    GM_addStyle ('body {background: ' + (sayHello.K % 2  ?  "lime"  :  "white") + ';}');
}
var gmObject        = {message: "Object overridden by GM."};

Open the console and press the buttons and you will see that the GM script is able to read and change the page's variables and functions.

---

Notes:

1. This is all Firefox specific.
2. For cross platform code, and for some complex situations, you can use Script Injection instead. But injected code cannot directly access GM_ functions.
3. Note that these techniques only work for javascript variables and functions that are global.

Wrap your code inside a lambda function like:

(function(window){      // and more arguments if you need it

  console.log(window);  // here, should be the real 'window'

})(window.unsafeWindow)