How does Backport work?

The global object is referenced by this from the global scope, it's the point of last resort for Javascript when it's looking for something. And it's where the JS API lives.

Because we can't alter the actual JS API (it's locked) there's only one option left - to override it further up the scope chain.

Most of your code runs in the global scope, such as your Event handlers and other top-level functions that they call. Unfortunately you can't define overrides in there because Javascript will find the original API features living in the global scope, see that they are locked, and throw a big fat error at you.

To make matters worse, we can't define overrides further up the scope chain, because we'd have to do it in lots of places. The only common point of reference, aside from the global object, is the global scope.

So, we need to find a way to create stuff in the global scope without the global object throwing errors at us.

Separating the global scope and global obeject

To do that, we need to make the global object disappear while we define our overrides. Luckily, Javascript's bag of tricks comes to the rescue: null

Null is a bit weird when compared to pretty much everything else in Javascript. It doesn't have any properties, or a prototype chain, or a scope.

So, by using Javascript's call() method, can we scope something to null and free ourselves from that troublesome error-throwing global object? Unfortunately, no. The call method simply adds a new scope to the start of our scope chain that contains one variable: this – and that variable is pointing to some other object and it's associated properties and prototype chain. The rest of our scope chain is unchanged, so any code we have in our functions will still have the dreaded global object lurking around waiting to throw errors at us.

Eval to the rescue!

Luckily, Javascript has another trick up it's sleeve: eval()

Evaluates a string of JavaScript code without reference to a particular object.

More accurately, eval() lets you run some fresh Javascript code in the global scope. There's just one problem, it brings a friend with it: The global object.

The global scope talks to it's friend via it's this variable. If only there was a way to change the value of this to something that doesn't lead back to the global object...

eval.call(null,someCode);

And there we have it: A way to run some code in the global scope without the troublesome global object joining the party.

It should be noted that it's only possible to do this because the JS environment in Warzone isn't running in strict mode. If it was, the call() method would spot our sneaky trick and scope everything back to the global object. Let's hope that Warzone never switches it's JS environment to strict mode!!

The backport() function in Backport.js is just an abstraction layer that writes some code for us and runs it in the global scope after hiding the global object. It enables us to inject stuff in to the global scope, without getting errors thrown at us. And, once we have something in the global scope, Javascript will find it first and not bother looking for it in the global object where the JS API lives.

Hang on...

But doesn't that mean that we can no longer get access to the stuff on the global object - the original JS API functions? It does, but luckily prototype chains come to the rescue.

From the global scope, you can still get to the global object via this. And to make live easier, backport keeps a handy reference to the global object as well: backport.global

So, let's assume we've used backport to delete the deprecated droidFromId() function (by setting it to undefined in the global scope), we can still access it (assuming it's still in the JS API) like this:

var gameObj = backport.global.droidFromId(someId);

Furthermore, to make things a little more descriptive, any functions that we override (to expose upgraded/extended alternatives) have a .native property that points back to the original JS API function.

For more information, see Accessing native API features.