Using 'using'

Explanation

Detox makes pretty heavy use of Haxe's "using" mixins. In short, these allow us to mix in some functions that aren't part of the original object, without having to wrap the object.

As an example, with JQuery on Javascript, you have to wrap native objects:

node = document.getElementById('small-child'); // get the raw DOM Node
jqueryObject = $(node);                        // wrap the node as a jQuery object so we can do stuff
jqueryObject.addClass('angry');                // jQuery functions can only be accessed through the wrapper.

You could do something similar with Haxe, say on the Flash target which uses Xml:

node = Xml.createElement('div');            // Get the raw Xml object
detoxCollection = new DOMCollection(node);  // We could wrap like this
detoxCollection.addClass('angry');

// OR, we could use it directly
node.addClass('angry');

So basically, this lets us use all of our Detox functionality on a normal DOM Node*.

(*) On Javascript, this is a DOM Node, on other targets, this is an Xml object.

Implications

For the most part, this doesn't make much difference, other than saving you have to remember to wrap your objects. There are some other things though:

• 'Using' is a compile time feature, and so the compiled code can look pretty different.

  So this: myNode.addClass('happy');

  Would output as: dtx.single.ElementManipulation.addClass(myNode, 'happy');

  Yes, I need to make that syntax less verbose ;)

• Because it's a comile time feature, it probably won't play nice with hscript, or with an interactive Javascript console for that matter.

• Because you're working with the native objects, you will have access to both the Detox methods and the native methods. Sometimes, these overlap. For example, on neko, these two methods do the same thing:

  myNode.setAttr('id', 'jason'); // the Detox method
  myNode.set('id', 'jason');     // the native method
  

  However, once you switch to Javascript, and the underlying object changes, the native method won't work. The Detox method however, will - it's been designed to be cross platform. So when possible, especially for cross-platform code, use the Detox methods instead of the native methods.

  In addition to being cross platform, the Detox option also prevents against errors being thrown with bad input etc.