1=encoding utf8 2 3=head1 NAME 4 5Jifty::Manual::JavaScript_zhtw - Jifty 之 JavaScript 程式設計指引 6 7=head1 DESCRIPTION 8 9jQuery took over Prototype and becoming the core of Jifty's Javascript 10development. Besides re-implementing core javascript libraries with 11jQuery, some good refactor is also being done. 12 13This document is written to help JavaScript programmers working for 14a Jifty project to understand what's the different before jQuery landed, 15and provide a quick reference for Prototypism believers to learn the new wave 16of JavaScript programming in Jifty. 17 18=head1 Migration to jQuery 19 20這部份提供了 jQuery 的核心函式的簡單指引。 21用來取代 Prototype 的 javascript 函式庫。 22 23=head2 Selecting elements with jQuery() 24 25Invoking the jQuery function with exactly one string argument will return 26a jQuery object that represents a list of elements. The string is 27a CSS selector. For example: 28 29 jQuery("span.message") 30 31This works very similar to Prototype's $$() function, but with one 32difference. The return value is I<not> an Array, it's a jQuery 33object that acts likes a Enumerable object (but still, not one). If you 34really want a Array, you can do: 35 36 var array_of_message = jQuery("span.message").get() 37 38For most cases, C<jQuery("#" + id).get(0)> can be a replacement pattern 39to C<$(id)>. Selecting elements with C<jQuery()> function always 40returns a jQuery object, but not element it self. There are two notice 41especially for Jifty world. 42 43First of all, Jifty developers should always use C<Jifty.$>. Deep in 44the design of Jifty, there are many kind of elements with C<":"> 45character in their id. Sadly it is a feature in jQuery to do more 46powerful selection with C<":"> character. For example, this selects 47current mouse-overed elements: 48 49 jQuery(":hover") 50 51C<jifty.js> internally use C<Jifty.$> as the direct replacement to 52C<$()> function defined in the Prototype library. 53 54However, for application developers it's quite safe to use 55C<jQuery("#id")> to select elements they created. 56 57=head2 Document ready with jQuery() 58 59The way to do execute some javascript right after the DOM is ready is 60to bind a handler for C<"ready"> event on the C<document> object: 61 62 jQuery(document).ready(function() { 63 ... 64 }); 65 66Since is done quite often, there's a shortcut: 67 68 jQuery(function() { 69 ... 70 }); 71 72=head1 METHODS 73 74This section list those public functions under C<Jifty> namespace. 75They are defined in jifty.js. 76 77=over 78 79=item Jifty.$( element_id ) 80 81This is a shorthand of C<document.getElementById> function, like the C<$> 82function defined in Prototype library. It is also internally used a 83lot because many form specific element ID does not get along with 84jQuery's selector, which expect the ":" character is used for special 85purpose. 86 87element_id should be a string. If not, element_id itself is returned. 88Therefore, this convention: 89 90 element = Jifty.$(element) 91 92Can work when the variable C<element> is either a string, or a HTML 93element object. 94 95=item Jifty.Effect(element, effect_name, option) 96 97When called, instantly perform a js effect on the given element. "element" is an 98element object. 99 100The last arg "option" is a hash. Currently it's only used for 101specifying callbacks. There are two possible callbacks, before and 102after. You may specify them like this: 103 104 Jifty.Effect(element, "Fade", { duration: 2.0 }, { 105 before: function() { ... }, 106 after: function() { ... } 107 }); 108 109The "before" callback is called right before the effect starts. 110The "after" callback is called right after it's started, but not 111necessarily ended. 112 113This function is written to make it possible that a Jifty plugin 114can override default effects with other fancy javascript libraries. 115By default, it delegates all the real work to jQuery's built-in 116effect functions. 117 118=item Jifty.Form.getElements(element) 119 120Given a form element, returns all input fields inside this form. That 121includes INPUT, SELECT, tags. The returned value is an array of HTML 122elements. 123 124=item Jifty.Form.getActions(element) 125 126Given a form element, returns a array of elements that are defined as 127Jifty actions. 128 129=item Jifty.Form.clearPlaceholders(element) 130 131=item Jifty.Form.Element.getMoniker( element ) 132 133Given an element, or an element id, return a string representing a 134moniker of this element. It returns null if the given element is 135considered having no moniker at all. 136 137=item Jifty.Form.Element.getAction( element ) 138 139Takes an element or an element id. Get the action for this form 140element. The returned value is an Action object. 141 142=item Jifty.Form.Element.getType( element ) 143 144Takes an element or an element id, returns the type associated with 145this element. Possible return values are "registration", "value", 146"fallback", or null if the element does not belongs to any of these 147types. 148 149=item Jifty.Form.Element.getField( element ) 150 151Takes an element or an element id, returns the name of it. Returns 152null if the element given does not have a name. 153 154=item Jifty.Form.Element.getValue( element ) 155 156Takes an element or an element id, returns the element value. If the 157element is a CHECKBOX or a RADIO button but it's unchecked, returns 158null. 159 160=item Jifty.Form.Element.validate( element ) 161 162Validates the action this form element is part of. 163 164=item Jifty.Form.Element.disableValidation( element ) 165 166Temporarily disable validation. 167 168=item Jifty.Form.Element.enableValidation( element ) 169 170Re-enable validation. 171 172=item Jifty.Form.Element.getForm( element ) 173 174Look up the form that this element is part of. 175 176This is sometimes more complicated than you'd think because the form 177may not exist anymore, or the element may have been inserted into a 178new form. Hence, we may need to walk the DOM. 179 180Upon the failure of searching, null is returned. 181 182=item Jifty.Form.Element.buttonArguments( element ) 183 184Takes an element or an element id that is considered as a "button", 185which can be an <INPUT type="submit"> tag, or a <A> tag, returns the 186arguments on this element. 187 188If none, an empty object is returned. 189 190=item Jifty.Form.Element.buttonActions( element ) 191 192Takes an element or an element id that is considered as a "button", 193return array of actions on this element. 194 195If none, an empty array is returned. 196 197=item Jifty.Form.Element.buttonFormElements( element ) 198 199Takes an element or an element id that is considered as a "button", 200return an array of form elements that's just constructed based on the 201arguments on this element. 202 203If none, an empty array is returned. 204 205=item Jifty.Form.Element.clickDefaultButton( element ) 206 207Click the first button that will submit the action associated with the 208form element. 209 210=item Jifty.Form.Element.handleEnter( event ) 211 212Trap "Enter" key, and prevent it from doing any browser default 213behaviours. 214 215=item Jifty.update(options) 216 217This 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 C<onclick> or other L<Jifty::Web::Form::Element> event handlers, this method is generally used. 218 219The C<options> are passed as an object where the following attributes are available. 220 221=over 222 223=item actions 224 225This 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 C<action_arguments>. The values assigned to each moniker should be "1" to signify that that moniker should be submitted. 226 227For example, 228 229 Jifty.update({ 'actions': { 'new_entry': 1 } }); 230 231=item action_arguments 232 233This 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. 234 235For example, 236 237 Jifty.update({ 238 'actions': { 'new_entry': 1 }, 239 'action_arguments': { 'new_entry': { 'foo': 42, 'bar': 'blah' } } 240 }); 241 242This would submit the action for moniker C<new_entry> with whatever form elements are included on the page along with setting the parameter C<foo> to "42" and the parameter C<bar> to "blah". 243 244=item continuation 245 246TODO Please document this... 247 248=item fragments 249 250This 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: 251 252=over 253 254=item region 255 256This is the fully-qualified name of the region to manipulate. 257 258=item args 259 260These 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 L<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.) 261 262=item path 263 264This is the path of the fragment to use when modifying the region. 265 266=item element 267 268This is a special C<jQuery> selector to use to choose an element to update. If this is given, the C<region> value will be ignored and the first element matching this selector will be used instead. 269 270=item mode 271 272This determines what kind of update to perform. It may be one of the following: 273 274=over 275 276=item Replace 277 278The contents of the region or selected element will be completely replaced by the server response. 279 280=item Top 281 282The server response will be inserted within the region or selected element before the rest of the content. 283 284=item Bottom 285 286The server response will be inserted within the region or selected element after the rest of the content. 287 288=item Before 289 290The content returned by the server will be inserted immediately before and outside the given region or element. 291 292=item After 293 294The content returned by the server will be inserted immediately after and outside the given region or element. 295 296=back 297 298=item effect 299 300This is used to select the C<Jifty.Effect> to use when performing the modification. This is a string naming the effect. 301 302=back 303 304=back 305 306=back 307 308=head1 REFERENCE 309 310=over 311 312=item jQuery in 15 minutes 313 314L<http://www.slideshare.net/simon/jquery-in-15-minutes/> 315 316=item Learning jQuery in 30 minutes 317 318L<http://www.slideshare.net/simon/learning-jquery-in-30-minutes/> 319 320=item Prototype jQuery going from one to the other 321 322L<http://www.slideshare.net/remy.sharp/prototype-jquery-going-from-one-to-the-other/> 323 324=item jQuery Official Documentation 325 326L<http://docs.jquery.com/> 327 328=back 329 330=cut 331