trusty (3) Jifty::Manual::jQueryMigrationGuide.3pm.gz

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.