1HTML::Prototype(3)    User Contributed Perl Documentation   HTML::Prototype(3)
2
3
4

NAME

6       HTML::Prototype - Generate HTML and Javascript for the Prototype
7       library
8

SYNOPSIS

10           use HTML::Prototype;
11
12           my $prototype = HTML::Prototype->new;
13           print $prototype->auto_complete_field(...);
14           print $prototype->auto_complete_result(...);
15           print $prototype->auto_complete_stylesheet(...);
16           print $prototype->content_tag(...);
17           print $prototype->define_javascript_functions;
18           print $prototype->draggable_element(...);
19           print $prototype->drop_receiving_element(...);
20           print $prototype->evaluate_remote_response(...);
21           print $prototype->form_remote_tag(...);
22           print $prototype->in_place_editor(...);
23           print $prototype->in_place_editor_field(...);
24           print $prototype->in_place_editor_stylesheet(...);
25           print $prototype->javascript_tag(...);
26           print $prototype->link_to_function(...);
27           print $prototype->link_to_remote(...);
28           print $prototype->observe_field(...);
29           print $prototype->observe_form(...);
30           print $prototype->periodically_call_remote(...);
31           print $prototype->sortable_element(...);
32           print $prototype->submit_to_remote(...);
33           print $prototype->tag(...);
34           print $prototype->text_field_with_auto_complete(...);
35           print $prototype->update_element_function(...);
36           print $prototype->visual_effect(...);
37

DESCRIPTION

39       The module contains some code generators for Prototype, the famous
40       JavaScript OO library and the script.aculous extensions.
41
42       The Prototype library (http://prototype.conio.net/) is designed to make
43       AJAX easy.  Catalyst::Plugin::Prototype makes it easy to connect to the
44       Prototype library.
45
46       This is mostly a port of the Ruby on Rails helper tags for JavaScript
47       for use in Catalyst.
48
49   METHODS
50       $prototype->in_place_editor( $field_id, \%options )
51           Makes an HTML element specified by the DOM ID $field_id become an
52           in-place editor of a property.
53
54           A form is automatically created and displayed when the user clicks
55           the element, something like this:
56
57                   <form id="myElement-in-place-edit-form" target="specified url">
58                           <input name="value" text="The content of myElement"/>
59                           <input type="submit" value="ok"/>
60                           <a onClick="javascript to cancel the editing">cancel</a>
61                   </form>
62
63           The form is serialized and sent to the server using an Ajax call,
64           the action on the server should process the value and return the
65           updated value in the body of the reponse. The element will
66           automatically be updated with the changed value (as returned from
67           the server).
68
69           Required options are:
70
71           "url": Specifies the url where the updated value should be sent
72           after the user presses "ok".
73
74           Addtional options are:
75
76           "rows": Number of rows (more than 1 will use a TEXTAREA)
77
78           "cols": The number of columns the text area should span (works for
79           both single line or multi line).
80
81           "size": Synonym for ‘cols’ when using single-line (rows=1) input
82
83           "cancel_text": The text on the cancel link. (default: "cancel")
84
85           "form_class_name": CSS class used for the in place edit form.
86           (default: "inplaceeditor-form")
87
88           "save_text": The text on the save link. (default: "ok")
89
90           "saving_class_name": CSS class added to the element while
91           displaying "Saving..."  (removed when server responds). (default:
92           "inplaceeditor-saving")
93
94           "load_text_url": Will cause the text to be loaded from the server
95           (useful if your text is actually textile and formatted on the
96           server)
97
98           "loading_text": If the "load_text_url" option is specified then
99           this text is displayed while the text is being loaded from the
100           server. (default: "Loading...")
101
102           "click_to_edit_text": The text on the click-to-edit link. (default:
103           "click to edit")
104
105           "external_control": The id of an external control used to enter
106           edit mode.
107
108           "ajax_options": Pass through options to the AJAX call (see
109           prototype's Ajax.Updater)
110
111           "with": JavaScript snippet that should return what is to be sent in
112           the Ajax call, "form" and "value" are implicit parameters
113
114       $prototype->in_place_editor_field( $object, $method, \%tag_options,
115       \%in_place_editor_options )
116           Renders the value of the specified object and method with in-place
117           editing capabilities.
118
119       $prototype->in_place_editor_stylesheet
120           Returns the in_place_editor stylesheet.
121
122       $prototype->auto_complete_field( $field_id, \%options )
123           Adds Ajax autocomplete functionality to the text input field with
124           the DOM ID specified by $field_id.
125
126           This function expects that the called action returns a HTML <ul>
127           list, or nothing if no entries should be displayed for
128           autocompletion.
129
130           Required options are:
131
132           "url": Specifies the URL to be used in the AJAX call.
133
134           Addtional options are:
135
136           "update": Specifies the DOM ID of the element whose  innerHTML
137           should be updated with the autocomplete entries returned by the
138           Ajax request.  Defaults to field_id + '_auto_complete'.
139
140           "with": A Javascript expression specifying the parameters for the
141           XMLHttpRequest.  This defaults to 'value', which in the evaluated
142           context refers to the new field value.
143
144           "indicator": Specifies the DOM ID of an elment which will be
145           displayed Here's an example using Catalyst::View::Mason with an
146           indicator against the auto_complete_result example below on the
147           server side.  Notice the 'style="display:none"' in the indicator
148           <span>.
149
150                   <% $c->prototype->define_javascript_functions %>
151
152                   <form action="/bar" method="post" id="baz">
153                   <fieldset>
154                           <legend>Type search terms</legend>
155                           <label for="acomp"><span class="field">Search:</span></label>
156                           <input type="text" name="acomp" id="acomp"/>
157                           <span style="display:none" id="acomp_stat">Searching...</span><br />
158                   </fieldset>
159                   </form>
160
161                   <span id="acomp_auto_complete"></span><br/>
162
163                   <% $c->prototype->auto_complete_field( 'acomp', { url => '/autocomplete', indicator => 'acomp_stat' } ) %>
164
165           while autocomplete is running.
166
167           "tokens": A  string or an array of strings containing separator
168           tokens for tokenized incremental autocompletion. Example: "<tokens
169           =" ','>> would allow multiple autocompletion entries, separated by
170           commas.
171
172           "min_chars": The minimum number of characters that should be in the
173           input field before an Ajax call is made to the server.
174
175           "on_hide": A Javascript expression that is called when the
176           autocompletion div is hidden. The expression should take two
177           variables: element and update.  Element is a DOM element for the
178           field, update is a DOM element for the div from which the innerHTML
179           is replaced.
180
181           "on_show": Like on_hide, only now the expression is called then the
182           div is shown.
183
184           "select": Pick the class of the element from which the value for
185           insertion should be extracted. If this is not specified, the entire
186           element is used
187
188       $prototype->auto_complete_result(\@items, $fieldname, [$phrase])
189           Returns a list, to communcate with the Autocompleter.
190
191           Here's an example for Catalyst:
192
193               sub autocomplete : Global {
194                   my ( $self, $c ) = @_;
195                   my @items = qw/foo bar baz/;
196                   $c->res->body( $c->prototype->auto_complete_result(\@items) );
197               }
198
199       $prototype->text_field_with_auto_complete($method, [\%tag_options],
200       [\%completion_options])
201           Wrapper for text_field with added Ajax autocompletion
202           functionality.
203
204           In your controller, you'll need to define an action called
205           auto_complete_for_object_method to respond the AJAX calls,
206
207       $prototype->auto_complete_stylesheet
208           Returns the auto_complete stylesheet.
209
210       $prototype->content_tag( $name, $content, \%html_options )
211           Returns a block with opening tag, content, and ending tag. Useful
212           for autogenerating tags like <a
213           href="http://catalyst.perl.org"Catalyst Homepage</a>>. The first
214           parameter is the tag name, i.e. 'a' or 'img'.
215
216       $prototype->text_field( $name, $method, $html_options )
217           Returns an input tag of the "text" type tailored for accessing a
218           specified attribute (identified by $method) on an object assigned
219           to the template (identified by $object). Additional options on the
220           input tag can be passed as a hash ref with $html_options.
221
222       $prototype->define_javascript_functions
223           Returns the library of JavaScript functions and objects, in a
224           script block.
225
226           Notes for Catalyst users:
227
228           You can use "script/myapp_create.pl Prototype" to generate a static
229           JavaScript file which then can be included via remote "script" tag.
230
231       $prototype->draggable_element( $element_id, \%options )
232           Makes the element with the DOM ID specified by "element_id"
233           draggable.
234
235           Example:
236
237               $prototype->draggable_element( 'my_image', { revert => 'true' } );
238
239           The available options are:
240
241           handle
242               Default: none. Sets whether the element should only be
243               draggable by an embedded handle. The value is a string
244               referencing a CSS class. The first child/grandchild/etc.
245               element found within the element that has this CSS class will
246               be used as the handle.
247
248           revert
249               Default: false. If set to true, the element returns to its
250               original position when the drags ends.
251
252           constraint
253               Default: none. If set to 'horizontal' or 'vertical' the drag
254               will be constrained to take place only horizontally or
255               vertically.
256
257           change
258               Javascript callback function called whenever the Draggable is
259               moved by dragging. It should be a string whose contents is a
260               valid JavaScript function definition. The called function gets
261               the Draggable instance as its parameter. It might look
262               something like this:
263
264                   'function (element) { // do something with dragged element }'
265
266           See http://script.aculo.us for more documentation.
267
268       $prototype->drop_receiving_element( $element_id, \%options )
269           Makes the element with the DOM ID specified by "element_id" receive
270           dropped draggable elements (created by draggable_element).
271
272           And make an AJAX call.
273
274           By default, the action called gets the DOM ID of the element as
275           parameter.
276
277           Example:
278               $prototype->drop_receiving_element(
279                 'my_cart', { url => 'http://foo.bar/add' } );
280
281           Required options are:
282
283           url The URL for the AJAX call.
284
285           Additional options are:
286
287           accept
288               Default: none. Set accept to a string or an array of strings
289               describing CSS classes. The Droppable will only accept
290               Draggables that have one or more of these CSS classes.
291
292           containment
293               Default: none. The droppable will only accept the Draggable if
294               the Draggable is contained in the given elements (or element
295               ids). Can be a single element or an array of elements. This is
296               option is used by Sortables to control Drag-and-Drop between
297               Sortables.
298
299           overlap
300               Default: none. If set to 'horizontal' or 'vertical' the
301               droppable will only react to a Draggable if it overlaps by more
302               than 50% in the given direction. Used by Sortables.
303
304               Additionally, the following JavaScript callback functions can
305               be used in the option parameter:
306
307           onHover
308               Javascript function called whenever a Draggable is moved over
309               the Droppable and the Droppable is affected (would accept it).
310               The callback gets three parameters: the Draggable, the
311               Droppable element, and the percentage of overlapping as defined
312               by the overlap option. Used by Sortables. The function might
313               look something like this:
314
315                   'function (draggable, droppable, pcnt) { // do something }'
316
317           See http://script.aculo.us for more documentation.
318
319       $prototype->evaluate_remote_response
320           Returns 'eval(request.responseText)' which is the Javascript
321           function that form_remote_tag can call in :complete to evaluate a
322           multiple update return document using update_element_function
323           calls.
324
325       $prototype->form_remote_tag(\%options)
326           Returns a form tag that will submit in the background using
327           XMLHttpRequest, instead of the regular reloading POST arrangement.
328
329           Even though it is using JavaScript to serialize the form elements,
330           the form submission will work just like a regular submission as
331           viewed by the receiving side.
332
333           The options for specifying the target with "url" and defining
334           callbacks are the same as "link_to_remote".
335
336       $prototype->javascript_tag( $content, \%html_options )
337           Returns a javascript block with opening tag, content and ending
338           tag.
339
340       $prototype->link_to_function( $name, $function, \%html_options )
341           Returns a link that will trigger a JavaScript function using the
342           onClick handler and return false after the fact.
343
344           Examples:
345
346               $prototype->link_to_function( "Greeting", "alert('Hello world!') )
347               $prototype->link_to_function( '<img src="really.png"/>', 'do_delete()', { entities => '' } )
348
349       $prototype->link_to_remote( $content, \%options, \%html_options )
350           Returns a link to a remote action defined by options "url" that's
351           called in the background using XMLHttpRequest.
352
353           The result of that request can then be inserted into a DOM object
354           whose id can be specified with options->{update}.
355
356           Examples:
357
358               $prototype->link_to_remote( 'Delete', {
359                   update => 'posts',
360                   url    => 'http://localhost/posts/'
361               } )
362
363               $prototype->link_to_remote( '<img src="refresh.png"/>', {
364                   update => 'emails',
365                   url    => 'http://localhost/refresh/'
366               } )
367
368           By default, these remote requests are processed asynchronously,
369           during which various callbacks can be triggered (e.g. for progress
370           indicators and the like).
371
372           Example:
373
374               $prototype->link_to_remote( 'count', {
375                   url => 'http://localhost/count/',
376                   complete => 'doStuff(request)'
377               } )
378
379           The callbacks that may be specified are:
380
381           "loading": Called when the remote document is being loaded with
382           data by the browser.
383
384           "loaded": Called when the browser has finished loading the remote
385           document.
386
387           "interactive": Called when the user can interact with the remote
388           document, even though it has not finished loading.
389
390           "complete": Called when the XMLHttpRequest is complete.
391
392           If you do need synchronous processing (this will block the browser
393           while the request is happening), you can specify $options->{type} =
394           'synchronous'.
395
396           You can customize further browser side call logic by passing in
397           Javascript code snippets via some optional parameters. In their
398           order of use these are:
399
400           "confirm": Adds confirmation dialog.
401
402           "condition":  Perform remote request conditionally by this
403           expression.  Use this to describe browser-side conditions when
404           request should not be initiated.
405
406           "before": Called before request is initiated.
407
408           "after": Called immediately after request was initiated and before
409           "loading".
410
411       $prototype->observe_field( $id, \%options)
412           Observes the field with the DOM ID specified by $id and makes an
413           Ajax when its contents have changed.
414
415           Required options are:
416
417           "frequency": The frequency (in seconds) at which changes to this
418           field will be detected.
419
420           "url": url to be called when field content has changed.
421
422           Additional options are:
423
424           "update": Specifies the DOM ID of the element whose innerHTML
425           should be updated with the XMLHttpRequest response text.
426
427           "with": A JavaScript expression specifying the parameters for the
428           XMLHttpRequest.  This defaults to value, which in the evaluated
429           context refers to the new field value.
430
431           Additionally, you may specify any of the options documented in
432           "link_to_remote".
433
434           Example TT2 template in Catalyst:
435
436               [% c.prototype.define_javascript_functions %]
437               <h1>[% page.title %]</h1>
438               <div id="view"></div>
439               <textarea id="editor" rows="24" cols="80">[% page.body %]</textarea>
440               [% url = base _ 'edit/' _ page.title %]
441               [% c.prototype.observe_field( 'editor', {
442                   url    => url,
443                   with   => "'body='+value",
444                   update => 'view'
445               } ) %]
446
447       $prototype->observe_form( $id, \%options )
448           Like "observe_field", but operates on an entire form identified by
449           the DOM ID $id.
450
451           Options are the same as "observe_field", except the default value
452           of the "with" option evaluates to the serialized (request string)
453           value of the form.
454
455       $prototype->periodically_call_remote( \%options )
456           Periodically calls the specified url $options->{url}  every
457           $options->{frequency} seconds (default is 10).
458
459           Usually used to update a specified div $options->{update} with the
460           results of the remote call.
461
462           The options for specifying the target with "url" and defining
463           callbacks is the same as "link_to_remote".
464
465       $prototype->sortable_element( $element_id, \%options )
466           Makes the element with the DOM ID specified by $element_id sortable
467           by drag-and-drop and make an Ajax call whenever the sort order has
468           changed. By default, the action called gets the serialized sortable
469           element as parameters.
470
471           Example:
472               $prototype->sortable_element( 'my_list', { url =>
473           'http://foo.bar/baz' } );
474
475           In the example, the action gets a "my_list" array parameter
476           containing the values of the ids of elements the sortable consists
477           of, in the current order.
478
479           You can change the behaviour with various options, see
480           http://script.aculo.us for more documentation.
481
482       $prototype->submit_to_remote( $name, $value, \%options )
483           Returns a button input tag that will submit a form using
484           XMLHttpRequest in the background instead of a typical reloading via
485           POST.
486
487           "options" argument is the same as in "form_remote_tag"
488
489       $prototype->tag( $name, \%options, $starttag );
490           Returns a opening tag.
491
492       $prototype->update_element_function( $element_id, \%options, \&code )
493           Returns a Javascript function (or expression) that'll update a DOM
494           element according to the options passed.
495
496           "content": The content to use for updating.  Can be left out if
497           using block, see example.
498
499           "action": Valid options are "update" (assumed by default), :empty,
500           :remove
501
502           "position": If the :action is :update, you can optionally specify
503           one of the following positions: :before, :top, :bottom, :after.
504
505           Example:
506               $prototype->javascript_tag(
507           $prototype->update_element_function(
508                   'products', { position => 'bottom', content => '<p>New
509           product!</p>'
510               ) );
511
512           This method can also be used in combination with remote method call
513           where the result is evaluated afterwards to cause multiple updates
514           on a page.
515
516           Example:
517                # View
518               $prototype->form_remote_tag( {
519                   url      => { "http://foo.bar/buy" },
520                   complete => $prototype->evaluate_remote_response
521               } );
522
523               # Returning view
524               $prototype->update_element_function( 'cart', {
525                   action   => 'update',
526                   position => 'bottom',
527                   content  => "<p>New Product: $product_name</p>"
528               } );
529               $prototype->update_element_function( 'status',
530                   { binding => "You've bought a new product!" } );
531
532       $prototype->visual_effect( $name, $element_id, \%js_options )
533           Returns a JavaScript snippet to be used on the Ajax callbacks for
534           starting visual effects.
535
536               $prototype->link_to_remote( 'Reload', {
537                   update   => 'posts',
538                   url      => 'http://foo.bar/baz',
539                   complete => $prototype->visual_effect( 'highlight', 'posts', {
540                       duration => '0.5'
541                   } )
542               } );
543

SEE ALSO

545       Catalyst::Plugin::Prototype, Catalyst.  <http://prototype.conio.net/>
546

AUTHOR

548       Sascha Kiefer, "esskar@cpan.org" Sebastian Riedel, "sri@oook.de" Marcus
549       Ramberg, "mramberg@cpan.org"
550
551       Built around Prototype by Sam Stephenson.  Much code is ported from
552       Ruby on Rails javascript helpers.
553

THANK YOU

555       Drew Taylor, Leon Brocard, Andreas Marienborg
556

LICENSE

558       This library is free software. You can redistribute it and/or modify it
559       under the same terms as perl itself.
560

POD ERRORS

562       Hey! The above document had some coding errors, which are explained
563       below:
564
565       Around line 111:
566           Non-ASCII character seen before =encoding in '‘cols’'. Assuming
567           CP1252
568
569
570
571perl v5.28.1                      2006-09-22                HTML::Prototype(3)
Impressum