NAME¶
jQueryMigrationGuide - How to migrate your code to use jQuery.
Migrate your jifty app to jquery¶
Application developers may start the migration by modifying
config.yml,
setting the "ConfigFileVersion" to 4. If you did not write any
custom javascript code for your app, then you're done. Everything should just
work.
If you did write some javascript code, but you did not use any of the functions
defined in
jifty*.js,
prototype.js or
scriptaculous.js,
then you're still good to go.
Otherwise, your code might need to be modified a little bit. Since both
prototype.js and
scriptaculous.js are removed by default, one
trivial choice is to simply bring them back. That is as easy as adding the
Prototypism plugin to your Jifty application.
If you dislike Prototypism like we do, you can choose to re-write your code with
jQuery. In the section "From Prototype to jQuery" below, we provide
some common patterns that can be applied to rewrite Prototypism code with
jQuery, or with just normal javascript.
If you hack on Jifty's internals, please make sure you've read the following
"Jifty API" section and Jifty::Manual::JavaScript to catch the
Javascript API updates since the removal of "prototype.js".
Although we've removed "prototype.js", we still prefer to use the
non-conflict mode of jQuery. That is, "$" function is now undefined
instead of an alias to jQuery. This is to ensure that it's not conflicting
with Prototypism anywhere. If you'd like to use "$" function, create
that alias in your "app.js" like this:
$ = jQuery;
However, instead of making a global alias, it's always recommended to localize
this alias within a closure:
(function($) {
// $ is an alias to jQuery only inside this closure
$(".message").show();
})(jQuery);
Jifty API¶
We re-architected Jifty's javascript libraries to use jQuery. Especially the
internal functions to process form elements.
The old, Prototype-based way is to extend Form object and the Form.Element
object. Since the removal of the Prototype library, it is dangerous to name
those functions under Form because loading the Prototype library can destroy
those Jifty functions.
The new jQuery-based way is to always extend internal functions under the Jifty
object. "Form" becomes "Jifty.Form",
"Form.Element" becomes "Jifty.Form.Element", and so on.
The detailed list of these functions are given in Jifty::Manual::Javascript.
Most of those functions are internal functions that you probably should not
use directly.
From Prototype to jQuery¶
If you've ever written javascript code for your Jifty applications, and you'd
like to remove the PrototypeJS library, here are some mechanical rules to
re-write prototype.js-based javascript code with jQuery.
Array iteration
From:
A.each( function( $_ ) { ... } )
To:
jQuery.each(A, function(index, value ) {
// "this" is an alias to current value.
})
Hash key iteration¶
From:
H = new Hash({...});
H.each(function( pair ) {
// pair.key is the key
// pair.value is the value
});
jQuery.each is designed to work on both "Array" and "Object"
in the same way. So there's not much difference.
To:
// H can be any kind of "Object"
jQuery.each(H, function(key, value) {
// "this" is an alias to current value.
})
Object extend¶
From:
obj.extend({ ... }}
To:
jQuery.extend( obj, { ... } )
JSON¶
jQuery does not ship with the JSON stringify function, but since it neither
altered the native Array, nor defined its own Hash, it's acceptable and
preferred to just use "JSON.stringify" from "json.js".
From:
// obj need to be one of those objects defined in C<prototype.js>
obj.toJSON();
To:
JSON.stringify( obj )
Effects¶
jQuery has a small set of default effects built into its core. They have
different names then those defined in "scriptaculous.js". The
internal way to specify effects is using the "Jifty.Effect" method.
Please see the detailed usage documentation in
Jifty::Manual::JavaScript.