Provided by: libjifty-perl_1.10518+dfsg-1ubuntu2_all bug

NAME

       Jifty::Manual::JavaScript_zhtw - Jifty aeXX JavaScript cXXaaXXeX-
       eXXaeXXaaXX

DESCRIPTION

       jQuery took over Prototype and becoming the core of Jifty's Javascript
       development. Besides re-implementing core javascript libraries with
       jQuery, some good refactor is also being done.

       This document is written to help JavaScript programmers working for a
       Jifty project to understand what's the different before jQuery landed,
       and provide a quick reference for Prototypism believers to learn the
       new wave of JavaScript programming in Jifty.

Migration to jQuery

       eXXeXXaeXXaeXXaeXXaeXX jQuery cXXae XaaXXaaXXaaXXcXXcXXaaXXaeXXaaXXa~XX
       cXXaeXXaaXXaeXX Prototype cXX javascript aaXXaaXXaaXXa~XX

   Selecting elements with jQuery()
       Invoking the jQuery function with exactly one string argument will
       return a jQuery object that represents a list of elements. The string
       is a CSS selector. For example:

           jQuery("span.message")

       This works very similar to Prototype's $$() function, but with one
       difference. The return value is not an Array, it's a jQuery object that
       acts likes a Enumerable object (but still, not one). If you really want
       a Array, you can do:

           var array_of_message = jQuery("span.message").get()

       For most cases, "jQuery("#" + id).get(0)" can be a replacement pattern
       to "$(id)". Selecting elements with "jQuery()" function always returns
       a jQuery object, but not element it self. There are two notice
       especially for Jifty world.

       First of all, Jifty developers should always use "Jifty.$". Deep in the
       design of Jifty, there are many kind of elements with ":" character in
       their id. Sadly it is a feature in jQuery to do more powerful selection
       with ":" character. For example, this selects current mouse-overed
       elements:

           jQuery(":hover")

       "jifty.js" internally use "Jifty.$" as the direct replacement to "$()"
       function defined in the Prototype library.

       However, for application developers it's quite safe to use
       "jQuery("#id")" to select elements they created.

   Document ready with jQuery()
       The way to do execute some javascript right after the DOM is ready is
       to bind a handler for "ready" event on the "document" object:

           jQuery(document).ready(function() {
               ...
           });

       Since is done quite often, there's a shortcut:

           jQuery(function() {
               ...
           });

METHODS

       This section list those public functions under "Jifty" namespace.  They
       are defined in jifty.js.

       Jifty.$( element_id )
           This is a shorthand of "document.getElementById" function, like the
           "$" function defined in Prototype library. It is also internally
           used a lot because many form specific element ID does not get along
           with jQuery's selector, which expect the ":" character is used for
           special purpose.

           element_id should be a string. If not, element_id itself is
           returned.  Therefore, this convention:

               element = Jifty.$(element)

           Can work when the variable "element" is either a string, or a HTML
           element object.

       Jifty.Effect(element, effect_name, option)
           When called, instantly perform a js effect on the given element.
           "element" is an element object.

           The last arg "option" is a hash. Currently it's only used for
           specifying callbacks. There are two possible callbacks, before and
           after. You may specify them like this:

               Jifty.Effect(element, "Fade", { duration: 2.0 }, {
                   before: function() { ... },
                   after: function() { ... }
               });

           The "before" callback is called right before the effect starts.
           The "after" callback is called right after it's started, but not
           necessarily ended.

           This function is written to make it possible that a Jifty plugin
           can override default effects with other fancy javascript libraries.
           By default, it delegates all the real work to jQuery's built-in
           effect functions.

       Jifty.Form.getElements(element)
           Given a form element, returns all input fields inside this form.
           That includes INPUT, SELECT, tags. The returned value is an array
           of HTML elements.

       Jifty.Form.getActions(element)
           Given a form element, returns a array of elements that are defined
           as Jifty actions.

       Jifty.Form.clearPlaceholders(element)
       Jifty.Form.Element.getMoniker( element )
           Given an element, or an element id, return a string representing a
           moniker of this element. It returns null if the given element is
           considered having no moniker at all.

       Jifty.Form.Element.getAction( element )
           Takes an element or an element id. Get the action for this form
           element. The returned value is an Action object.

       Jifty.Form.Element.getType( element )
           Takes an element or an element id, returns the type associated with
           this element. Possible return values are "registration", "value",
           "fallback", or null if the element does not belongs to any of these
           types.

       Jifty.Form.Element.getField( element )
           Takes an element or an element id, returns the name of it. Returns
           null if the element given does not have a name.

       Jifty.Form.Element.getValue( element )
           Takes an element or an element id, returns the element value. If
           the element is a CHECKBOX or a RADIO button but it's unchecked,
           returns null.

       Jifty.Form.Element.validate( element )
           Validates the action this form element is part of.

       Jifty.Form.Element.disableValidation( element )
           Temporarily disable validation.

       Jifty.Form.Element.enableValidation( element )
           Re-enable validation.

       Jifty.Form.Element.getForm( element )
           Look up the form that this element is part of.

           This is sometimes more complicated than you'd think because the
           form may not exist anymore, or the element may have been inserted
           into a new form.  Hence, we may need to walk the DOM.

           Upon the failure of searching, null is returned.

       Jifty.Form.Element.buttonArguments( element )
           Takes an element or an element id that is considered as a "button",
           which can be an <INPUT type="submit"> tag, or a <A> tag, returns
           the arguments on this element.

           If none, an empty object is returned.

       Jifty.Form.Element.buttonActions( element )
           Takes an element or an element id that is considered as a "button",
           return array of actions on this element.

           If none, an empty array is returned.

       Jifty.Form.Element.buttonFormElements( element )
           Takes an element or an element id that is considered as a "button",
           return an array of form elements that's just constructed based on
           the arguments on this element.

           If none, an empty array is returned.

       Jifty.Form.Element.clickDefaultButton( element )
           Click the first button that will submit the action associated with
           the form element.

       Jifty.Form.Element.handleEnter( event )
           Trap "Enter" key, and prevent it from doing any browser default
           behaviours.

       Jifty.update(options)
           This function is used to handle most Jifty-related ajax requests.
           It handles the submission of actions, manipulation of
           continuations, and modification of page regions. Whenever building
           "onclick" or other Jifty::Web::Form::Element event handlers, this
           method is generally used.

           The "options" are passed as an object where the following
           attributes are available.

           actions
               This is an object declaring the monikers you wish to submit
               with the update. These actions will be taken based upon the
               form inputs and also the values described in
               "action_arguments". The values assigned to each moniker should
               be "1" to signify that that moniker should be submitted.

               For example,

                 Jifty.update({ 'actions': { 'new_entry': 1 } });

           action_arguments
               This specifies any additional arguments to submit with the
               action. These are specified as a object where the fields are
               the names of the monikers to submit arguments for. The values
               are objects describing the parameters to pass to the action.

               For example,

                 Jifty.update({
                     'actions': { 'new_entry': 1 },
                     'action_arguments': { 'new_entry': { 'foo': 42, 'bar': 'blah' } }
                 });

               This would submit the action for moniker "new_entry" with
               whatever form elements are included on the page along with
               setting the parameter "foo" to "42" and the parameter "bar" to
               "blah".

           continuation
               TODO Please document this...

           fragments
               This is an array describing modifications to make to page
               regions. Each element of the array is an object describing a
               single modification. The fields that are valid for each include
               the following:

               region
                   This is the fully-qualified name of the region to
                   manipulate.

               args
                   These are the arguments to pass to the server. These are
                   passed as an argument where the field names are the keys to
                   pass. The values may be a typical string value to pass in
                   or may be one of the special values listed in
                   Jifty::Request::Mapper, which will set the values based
                   upon action results and other values in the request. (Those
                   values will need to be produced using the JavaScript analog
                   of the descriptions in Perl. Specifically, hashes are
                   JavaScript objects and actions must be given as action
                   monikers.)

               path
                   This is the path of the fragment to use when modifying the
                   region.

               element
                   This is a special "jQuery" selector to use to choose an
                   element to update. If this is given, the "region" value
                   will be ignored and the first element matching this
                   selector will be used instead.

               mode
                   This determines what kind of update to perform. It may be
                   one of the following:

                   Replace
                       The contents of the region or selected element will be
                       completely replaced by the server response.

                   Top The server response will be inserted within the region
                       or selected element before the rest of the content.

                   Bottom
                       The server response will be inserted within the region
                       or selected element after the rest of the content.

                   Before
                       The content returned by the server will be inserted
                       immediately before and outside the given region or
                       element.

                   After
                       The content returned by the server will be inserted
                       immediately after and outside the given region or
                       element.

               effect
                   This is used to select the "Jifty.Effect" to use when
                   performing the modification. This is a string naming the
                   effect.

REFERENCE

       jQuery in 15 minutes
           http://www.slideshare.net/simon/jquery-in-15-minutes/
           <http://www.slideshare.net/simon/jquery-in-15-minutes/>

       Learning jQuery in 30 minutes
           http://www.slideshare.net/simon/learning-jquery-in-30-minutes/
           <http://www.slideshare.net/simon/learning-jquery-in-30-minutes/>

       Prototype jQuery going from one to the other
           http://www.slideshare.net/remy.sharp/prototype-jquery-going-from-one-to-the-other/
           <http://www.slideshare.net/remy.sharp/prototype-jquery-going-from-
           one-to-the-other/>

       jQuery Official Documentation
           <http://docs.jquery.com/>

perl v5.12.4                      2010-12-0Jifty::Manual::JavaScript_zhtw(3pm)