source: Dev/trunk/src/client/dojox/jq/README @ 529

-------------------------------------------------------------------------------
DojoX jq
-------------------------------------------------------------------------------
Version 0.0.1
Release date: 8/9/2009
-------------------------------------------------------------------------------
Project state:
experimental
-------------------------------------------------------------------------------
Credits
        James Burke
-------------------------------------------------------------------------------
Project description

DojoX jq is a compatibility layer that tries to match the jquery 1.3.2 API.
-------------------------------------------------------------------------------
Dependencies:

- Dojo Core.
-------------------------------------------------------------------------------
Documentation

IF YOU WISH TO WORK ON THIS MODULE, PLEASE DO NOT LOOK AT THE JQUERY SOURCE.

We want CLA-clean code to be put in the Dojo repos. Just refer to the jquery API
documentation and unit tests. As we get bug reports, we can build up our own test
suite, and then hopefully contribute those tests back to jquery if their tests
do not adequately cover an API call.

This module needs a lot of work, it is in the very initial, rough stages. Some
(all?) of the code is ugly. It is missing some APIs, notably queue/dequeue,
the FX methods and live/die.

There are also some incompatibilities with how acme and sizzle operate at the moment,
mentioned in the comments in jq.js

The tests for this module so far have been the jquery 1.3.2 tests. Since those
tests are not CLA-clean, you will need to download them from here:

http://www.tagneto.org/dojo/jquery132.zip

Place the zip file in the dojox/jq/tests directory and unzip it. Then you can
run the jquery132/test/index.html file inside there to start the tests.

The tests were changed in a couple ways. For the tests I modified,
you can look for //JRB changed: to find the original test construction.
Things that were changed:

1) acme requires spaces between CSS3 selectors, where sizzle does
not ("div>span" fails in acme, but works in sizzle). There is a
dtk.org bug on it, and it is allowed by the CSS3 spec to not have
spaces so hopefully that incompatibility can go away after a while.

2) sizzle supports some psuedos like :last, :first: :odd, :even that
work on the list of matched elements, not just individual elements or
their children. This is a more fundamental change to acme, but it is probably
doable.

3) The XML tests and ajax tests that call out to files fail because of
some weird timing interaction between the jquery unit test thing and
our XHR code. I believe since our code has a timer where we check the
status of the XHR calls instead of using load callbacks directly on
the XHR callbacks, something is confused in jquery -- the failure case
is fired before our callbacks work. If only they used deferreds. ;)
To get those tests to sort of work, I modified qunit/testrunner.js's process()
method to be like so:

function process() {
        if(config.queue.length && !config.blocking){
                setTimeout(function(){
                if(config.queue.length && !config.blocking){
                        config.queue.shift()();
                        process();
                }
                }, 100);
        }
}

Change 100 above to tune it depending on your patience and how much
you want to make sure the tests have enough time to run. With 100, you
can see some of the ajax tests passing.

From some previous notes (I have not checked more recently), it looks
like the compat layer fires "ajaxStop" more than jquery, I think due
to how we do our async in-flight testing, so that messes up some of
the testing in the ajax calls, but I think that is a detail that is
fine to go with. I just have to make sure that is really the cause of
a test failure and not something else. So I will probably need to
modify the tests more.


-------------------------------------------------------------------------------
Installation instructions

Grab the following from the Dojo SVN Repository:
http://svn.dojotoolkit.org/src/dojox/trunk/jq.js
http://svn.dojotoolkit.org/src/dojox/trunk/jq/*

Install into the following directory structure:
/dojox/jq.js

...which should be at the same level as your Dojo checkout.
-------------------------------------------------------------------------------