Haxe 3

jQueryExtern version 2.0.0-alpha.1 supports Haxe 3. It does not support Haxe 2 anymore.

Following outlines the changes.

Generated from api.xml

The jQuery externs, including inline documentation, are now generated from api.xml, the official jQuery documentation in xml format . This will enable jQueryExtern to be synchronized with the latest version of jQuery much faster and easier.

For your information, the generator is jQuery.haxe.gen.CoreExternGenerator. One can re-generate the externs by the following hxml:

-neko CoreExternGenerator.n
-main jQuery.haxe.gen.CoreExternGenerator
-cmd neko CoreExternGenerator.n api.xml .

New module structure

Individual jQuery classes are now split into their own modules(files) instead of living in the single jQuery.JQuery module.

They can now be easily accessed by

import jQuery.*; //previously `import jQuery.JQuery;`

Haxe related classes are put into jQuery.haxe, including Config, Plugin etc.

Config

A jQuery.haxe.Config class is introduced to enable more flexible jQuery configuration.

setVersion

By default, jQueryExtern provides API of the latest version of jQuery, which is currently 1.9.1 / 2.0.0 (they share the same API, but 2.0.0 removed support of IE6,7,8). We can now also specify the jQuery API version to be used (e.g. 1.8.3) by adding the following compiler option:

--macro jQuery.haxe.Config.setVersion('1.8.3')

In such case, all APIs that are removed/deprecated since 1.8.3, and the not yet added 1.9.x API, wouldn't be available in the extern. As a result, we wouldn't accidentally call an API that is not available.

We can also optionally keep the deprecated (not yet removed) APIs by:

--macro jQuery.haxe.Config.allowDeprecated(true)

setNative

jQuery is normally referred as $ in run-time, which is an alise of jQuery. Some JS libs, eg. PrototypeJS also use the $ variable, so we may want to refer jQuery by its original name instead.

To do so, add the following compiler option:

--macro jQuery.haxe.Config.setNative('jQuery')

Previously it is done by -D JQUERY_NOCONFLICT.

Plugin

A jQuery.haxe.Plugin class is introduced to ease the process of writing jQuery plugin extern. It is macro-based, responsible for copy-and-pasting the fields in the extern classes into jQuery.JQuery and jQuery.JQueryStatic.

To write a jQuery plugin extern, create an extern class that implements jQuery.haxe.Plugin, and start writing the members as if writing directly inside the jQuery.JQuery/jQuery.JQueryStatic class.

package pack;

import jQuery.*;

extern class JQueryPlugIn implements jQuery.haxe.Plugin {
    //instance members will go to `jQuery.JQuery`
    public function myMethod(arg:Dynamic):JQuery;
    
    //static members will go to `jQuery.JQueryStatic`
    static public function myStaticMethod(arg:Dynamic):JQueryStatic;
}

To use it, add the following compiler option:

--macro jQuery.haxe.Config.addPlugin('pack.JQueryPlugIn')

TODOs

Following are some pending changes will be introduced in later versions of jQueryExtern.

• Review all the signatures and try to eliminate more Dynamic by @:overload.
• Add iterator(). Haxe 3 allows iterating object that implements ArrayAccess and has a length property.
• Complete the jQueryTools and jQueryUI externs. Too much workload at the moment. May create separated project for that in the future.
• Look into if we want to add a type param for the containing elements (constrained to js.html.Element). Too hard to handle it right.