.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Jifty::Manual::jQueryMigrationGuide 3pm"
.TH Jifty::Manual::jQueryMigrationGuide 3pm "2010-12-08" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
jQueryMigrationGuide \- How to migrate your code to use jQuery.
.SH "Migrate your jifty app to jquery"
.IX Header "Migrate your jifty app to jquery"
Application developers may start the migration by modifying
\&\fIconfig.yml\fR, setting the \f(CW\*(C`ConfigFileVersion\*(C'\fR to 4. If you did not write
any custom javascript code for your app, then you're done. Everything
should just work.
.PP
If you did write some javascript code, but you did not use any
of the functions defined in \fIjifty*.js\fR, \fIprototype.js\fR or
\&\fIscriptaculous.js\fR, then you're still good to go.
.PP
Otherwise, your code might need to be modified a little bit. Since
both \fIprototype.js\fR and \fIscriptaculous.js\fR are removed by default,
one trivial choice is to simply bring them back. That is as easy as
adding the \fBPrototypism\fR plugin to your Jifty application.
.PP
If you dislike Prototypism like we do, you can choose to
re-write your code with jQuery. In the section \*(L"From Prototype
to jQuery\*(R" below, we provide some common patterns that can be applied to
rewrite Prototypism code with jQuery, or with just normal javascript.
.PP
If you hack on Jifty's internals, please make sure you've read the following
\&\*(L"Jifty \s-1API\s0\*(R" section and Jifty::Manual::JavaScript to catch the
Javascript \s-1API\s0 updates since the removal of \f(CW\*(C`prototype.js\*(C'\fR.
.PP
Although we've removed \f(CW\*(C`prototype.js\*(C'\fR, we still prefer to use
the non-conflict mode of jQuery. That is, \f(CW\*(C`$\*(C'\fR 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 \f(CW\*(C`$\*(C'\fR function, create that alias in your \f(CW\*(C`app.js\*(C'\fR like this:
.PP
.Vb 1
\&    $ = jQuery;
.Ve
.PP
However, instead of making a global alias, it's always recommended to
localize this alias within a closure:
.PP
.Vb 2
\&    (function($) {
\&        // $ is an alias to jQuery only inside this closure
\&
\&        $(".message").show();
\&    })(jQuery);
.Ve
.SH "Jifty API"
.IX Header "Jifty API"
We re-architected Jifty's javascript libraries to use jQuery. Especially
the internal functions to process form elements.
.PP
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.
.PP
The new jQuery-based way is to always extend internal functions
under the Jifty object. \f(CW\*(C`Form\*(C'\fR becomes \f(CW\*(C`Jifty.Form\*(C'\fR, \f(CW\*(C`Form.Element\*(C'\fR becomes
\&\f(CW\*(C`Jifty.Form.Element\*(C'\fR, 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.
.SH "From Prototype to jQuery"
.IX Header "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.
.PP
\fIArray iteration\fR
.IX Subsection "Array iteration"
.PP
From:
.PP
.Vb 1
\&    A.each( function( $_ ) { ... } )
.Ve
.PP
To:
.PP
.Vb 3
\&    jQuery.each(A, function(index, value ) {
\&        // "this" is an alias to current value.
\&    })
.Ve
.SS "Hash key iteration"
.IX Subsection "Hash key iteration"
From:
.PP
.Vb 1
\&    H = new Hash({...});
\&
\&    H.each(function( pair ) {
\&        // pair.key is the key
\&        // pair.value is the value
\&    });
.Ve
.PP
jQuery.each is designed to work on both \f(CW\*(C`Array\*(C'\fR and \f(CW\*(C`Object\*(C'\fR in the
same way. So there's not much difference.
.PP
To:
.PP
.Vb 1
\&    // H can be any kind of "Object"
\&
\&    jQuery.each(H, function(key, value) {
\&        // "this" is an alias to current value.
\&    })
.Ve
.SS "Object extend"
.IX Subsection "Object extend"
From:
.PP
.Vb 1
\&    obj.extend({ ... }}
.Ve
.PP
To:
.PP
.Vb 1
\&    jQuery.extend( obj, { ... } )
.Ve
.SS "\s-1JSON\s0"
.IX Subsection "JSON"
jQuery does not ship with the \s-1JSON\s0 stringify function, but since it
neither altered the native Array, nor defined its own Hash, it's
acceptable and preferred to just use \f(CW\*(C`JSON.stringify\*(C'\fR from \f(CW\*(C`json.js\*(C'\fR.
.PP
From:
.PP
.Vb 2
\&    // obj need to be one of those objects defined in C<prototype.js>
\&    obj.toJSON();
.Ve
.PP
To:
.PP
.Vb 1
\&    JSON.stringify( obj )
.Ve
.SS "Effects"
.IX Subsection "Effects"
jQuery has a small set of default effects built into its core. They
have different names then those defined in \f(CW\*(C`scriptaculous.js\*(C'\fR. The
internal way to specify effects is using the \f(CW\*(C`Jifty.Effect\*(C'\fR method. Please
see the detailed usage documentation in Jifty::Manual::JavaScript.