Andy Li’s Blog - jQuery

New jQuery Extern arrived at Haxe Standard Library

2015-07-02T00:00:00+08:00

jQuery has been ~~one of~~ the most popular JavaScript library in the world. To help existing JS developers switch to Haxe for a modern language with accurate static typing, a complete and up-to-date jQuery extern is necessary.

As I’ve mentioned in the previous post, I’m working on updating the jQuery extern in the Haxe standard library. Today, I’ve just committed the initial work to the Haxe repo. The new extern is generated by the same script that powers jQueryExtern. The resulting extern matches perfectly with the latest jQuery API (1.11.3 / 2.1.4). And since it is generated, we can update the extern very easily when there is a new jQuery release (I used less than an hour for each of the previous updates to jQueryExtern).

The differences between the old and the new externs are detailed at Github issue #4377, where you may report any migration issue or provide any feedback. Go ahead and get a development build of Haxe and play with the new extern!

jQueryExtern 2.0.0-alpha.1

2013-05-14T11:54:00+08:00

It took longer than expected, but jQueryExtern for Haxe 2.0.0-alpha.1 was released to haxelib!

The cool parts:

Supports jQuery version 1.9.1/2.0.0! Note that 2.0.0 has the same API of 1.9.1, but removed support of IE 6,7,8.
jQueryExtern is now generated from the official jQuery documentation in XML format. It means it will be updated faster, more accurate in the future!
Fine grained configuration of the extern via… macros! e.g. Select specific jQuery support version, switching between the use of $ or jQuery in generated code etc.
Macro based Plugin extern system! Writing jQuery plugin extern is much easier.

You can find out the details at the Github wiki page.

Haxe tips: better untyped expression

2012-07-08T04:20:00+08:00

tl;dr

Remember to put the brackets

    (untyped new JQuery("#images").imageLoader)({});
//  ^                                         ^
//  |________these____________________________|

Abstract

Static type system of Haxe helps you a lot by performing type-checking in the compilation phase. You will be notified errors before the application is run.

Since some Haxe targets (e.g.. JS and PHP) are dynamic in nature, many of the native libraries/frameworks are also very dynamic. You have to use the untyped keyword in Haxe very often to workaround the compiler type-checking.

As a best-practice, to avoid unnecessary suppression of type-checking, brackets should always be placed in order to constrain affecting slope when using the untyped keyword in an expression.

Example: using jQuery plug-in

For illustration, I will explain a frequently faced problem that is how to use jQuery plug-in in Haxe (following will use jQueryExtern). In case there is a plug-in that will add a method, .imageLoader(config), to jQuery. But since there is no such method declared in the JQuery extern class, if you simply compile new JQuery("#images").imageLoader({});, it will certainly fail with error “jQuery.JQuery has no field imageLoader“.

You have two options:

Create a plugin class and then “using” it.
Use a quick and dirty untyped keyword.

For 1, you can refer to some experimental plug-in externs from jQueryExtern. Read my blog post on how to use it with ”using”. This method takes some more amount of coding and does not work well with optional arguments.

For 2, adding a untyped keyword will shut the complier’s mouth up: untyped new JQuery("#images").imageLoader({});.

The above of course works, but you will lose many type-checking in the expression where are unnecessarily suppressed. e.g.. if you forgot to define config in

untyped new JQuery("#images").imageLoader(config);

…it will compile and fails at runtime with “Uncaught ReferenceError: config is not defined“.

Instead, constrain the untyped scope by placing a pair of brackets:

(untyped new JQuery("#images").imageLoader)(config);

…it now (correctly) fails to be compiled with error “Unknown identifier : config“.

It is useful because sometimes you may code like this:

(untyped new JQuery("#images").imageLoader)({
    images: images,
    async: 10,
    complete: function(e, ui) {
        progressbar.progressbar("value" , (++loaded).map(0, numOfFrames, 0, 100));
    },
    allcomplete: function(e, ui:Array) {
        new JQuery(function(){
            var playback = new JQuery("#playback").html("");
            for (item in ui) {
                new JQuery(item.img)
                .attr("id", "playback-" + Std.string(item.i))
                .appendTo(playback)
                .hide();
            }

            if (displayMode.enumEq(PlaybackMode))
                imageLoop(12);

            new JQuery("#toggle-play-btn").removeAttr("disabled");
            new JQuery("#toggle-slow-btn").removeAttr("disabled");

            new JQuery("#main").removeClass("loading");
        });
    }
});

If you do not place brackets around untyped (at line 1 as shown above), you will unnecessarily lose type-checking for over 90% of codes (begin with line 2 of above), which is pretty bad.

haXe jQueryExtern update: align with 1.6.1, ‘jQuery’ package…

2011-06-12T00:00:00+08:00

I’ve recently updated jQueryExtern to align with jQuery 1.6.1. To get it, use the usual haxelib upgrade (or haxelib install jQueryExtern if you have not installed it previously).

I introduced some changes that would like to explain here:

package `jQuery`

Finally jQueryExtern has its own package, jQuery. The previous jQueryPlugins package is also moved to jQuery.plugins.

It is done because jQuery has more and more types, e.g.. jqXHR, Deferred and Promise are introduced in jQuery 1.5. In the previous versions of jQueryExtern, most of them are prefixed by JQuery (JQueryPromise, JQueryDeferred, JQueryEvent) which is lengthy and redundant, with jQuery package, it is now safe to remove the prefix. In case of name collision, simply use the fully qualified names, e.g. jQuery.Event.

To conclude, you should now include jQuery.JQuery; instead of include JQuery;.

`JQueryStatic` and `_static`

To solve the problem of haXe disallowing the use of same name for static and non-static members, previously I grouped the static methods into a separate class JQueryS. It is now renamed as JQueryStatic, which is more meaningful.

I’ve also added a _static static property to JQuery. It is for the people who don’t read documentation, when they type JQuery., there is still a code completion _static for them to retrieve the JQueryStatic class.

Whether to use JQuery._static or JQueryStatic is up to you.

Backward compatibility and `JQUERY_NO_DEPRECATED`

Don’t worry on having to change all your production codes to match the changes mentioned above. I’ve included a top-level “JQuery.hx” for maintaining backward compatibility. A number of typedef are placed there to solve the old naming.

However, the old naming are deprecated and the top-level “JQuery.hx” will be removed a few versions later. You should try to update your code and test with -D JQUERY_NO_DEPRECATED.

The typedef trick have not been made for the plug-ins, so if you’re using any of the plug-ins, you have to make the changes when updating to jQueryExtern 1.6.1.

Using jQuery in haXe

2010-08-03T23:41:00+08:00

It is a kind of pain to code in JS without a proper library like jQuery. Using plain haXe in JS target is just as pain since haXe does not abstract most of the browser quirks, what it gives is only stricter typing and a little bit better core API (nothing DOM related…). When there is no solid haXe/JS targeted haxe library come out yet, we have to find some ways to use external JS libraries.

There is a jQuery wrapper appeared on haxelib last year, but I don’t really like its API, which is too different from the original one, and I’ve never used to having method names first letter capitalized… OK, it’s just personal taste :P Anyway I’ve written a jQuery extern to replace it, which provides API closer to jQuery and smaller compiled JS file (smaller because the haXe compiler does not generate codes for extern class).

Here I will illustrate a bit on how to use it, requiring you to have some experience on both haXe and jQuery.

Installing the jQuery extern

Since its put on haxelib, you can install it using the command:

haxelib install jQueryExtern

and then add -lib jQueryExtern in the hxml.

OR, you can download the cutting edge version from Github: http://github.com/andyli/jQueryExternForHaxe, extract and place “JQuery.hx” (optionally with the “jQueryPlugins” folder) into your project source directory.

Using the jQuery classes

It should be better to illustrate with example. For a typical JS starting point with jQuery, you write:

$(function(){
    //do your magic
});

If you don’t know, it’s a short-hand that bind your magic codes to the document ready event, same as you write:

$(document).ready(function(){
    //do your magic
});

HaXe does not allow using $ as a class name or a function name, but $ is just a short-hand to jQuery. However, haXe requires all class names start with capital letter, so it is JQuery not jQuery. You start your haXe/JS codes using the jQuery extern as following:

import JQuery;

class Main {
    static public function main():Void {
        new JQuery(function():Void {
            //your magic codes
        });
    }
}

It seems to be a few lines more than JS, but you should already know, the extra lines are the same for all other haXe targets, its how haXe program starts. The main point is new JQuery(...) which is the same as $(...) in JS.

So, when you code in JS like:

$("#myMightyDiv").hide();

now you do the same in haXe:

new JQuery("#myMightyDiv").hide();

Simple.

Static functions

One thing to aware, that is the static methods of jQuery are placed to JQueryS in the extern. The reason is haXe does not allow using same name for both static and instance methods. For example in the original jQuery, there is $.data() and $(...).data(), they are now in the extern as JQueryS.data() and new JQuery(...).data().

Extra methods in the jQuery extern

And there are some extra methods appears in the extern comparing to the original jQuery. For example, there is cssSet(), and it is just the same as css() but limiting you to really setting a CSS property and it is properly typed as returning a JQuery object, so you can happily chaining the methods with code completion and type checking. All the extra methods are like that and they are all set as inline, so that the haXe compiler will generate correct codes, that is css() not cssSet() in the compiled JS, because cssSet() is not really existing in jQuery. And because they are not really existing, don’t try to call the extra methods with Reflect.

Using plug-ins

I’ve included some jQuery plug-in externs. Currently there are jQuery Tools, jQuery media plug-in and jQuery UI (work-in-progress).

The plug-in architecture is a bit hard to deal with… To understand how it works, first of all you have to know there is a mighty “using” keyword in haXe, which inject methods into object instance. And the jQuery plug-in in my haXe extern is utilizing both “using” and “inline”.

Anyway, here is how you use the plug-ins. For example, when using jQuery Tools in JS, you just include its JS file in HTML and you can call the plug-in’s method on the jQuery object, that is:

$(".my_overlay_trigger").overlay({...}); //overlay is from jQuery Tools

In haXe, with my extern, you have to write:

import JQuery;
//there are several classes in Overlay.hx, we "using" only the "Overlay" class.
using jQueryPlugins.jQueryTools.Overlay.Overlay;

/* ... */

new JQuery(".my_overlay_trigger").overlay({/* ... */});

/* ... */

Because this implementation doesn’t deal with optional parameter very well, in most of the cases I made the optional parameters mandatory. If the method has a optional config parameter, but you just want to use the defaults, simply pass in {}.

And there are many cases some functions does not fit that well, I’ve wrap them into classes/methods with inline. You may have to look at the source file to fully understand how to use.

There will be more plug-ins to come when I need them. Feel free to integrate other plug-ins and let me put them into the extern.