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, this causes some overlap. Consider this example, these methods each do the same thing:

  myNode.setAttribute('id', 'jason'); // the native HtmlDom method, used by JS  
  myNode.set('id', 'jason');     // the native Xml method, used by Flash, CPP, Neko etc  
  myNode.setAttr('id', 'jason'); // the Detox method, works on all platforms.
  

  The Detox method however, has been designed to be completely 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.