1HTML::Prototype(3) User Contributed Perl Documentation HTML::Prototype(3)
2
6 HTML::Prototype - Generate HTML and Javascript for the Prototype
7 library
8
10 use HTML::Prototype;
11 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
39 The module contains some code generators for Prototype, the famous
40 JavaScript OO library and the script.aculous extensions.
41 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 This is mostly a port of the Ruby on Rails helper tags for JavaScript
47 for use in Catalyst.
48 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 A form is automatically created and displayed when the user clicks
55 the element, something like this:
56 <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 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 Required options are:
70 "url": Specifies the url where the updated value should be sent
72 after the user presses "ok".
73 Addtional options are:
75 "rows": Number of rows (more than 1 will use a TEXTAREA)
77 "cols": The number of columns the text area should span (works for
79 both single line or multi line).
80 "size": Synonym for ‘cols’ when using single-line (rows=1) input
82 "cancel_text": The text on the cancel link. (default: "cancel")
84 "form_class_name": CSS class used for the in place edit form.
86 (default: "inplaceeditor-form")
87 "save_text": The text on the save link. (default: "ok")
89 "saving_class_name": CSS class added to the element while
91 displaying "Saving..." (removed when server responds). (default:
92 "inplaceeditor-saving")
93 "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 "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 "click_to_edit_text": The text on the click-to-edit link. (default:
103 "click to edit")
104 "external_control": The id of an external control used to enter
106 edit mode.
107 "ajax_options": Pass through options to the AJAX call (see
109 prototype's Ajax.Updater)
110 "with": JavaScript snippet that should return what is to be sent in
112 the Ajax call, "form" and "value" are implicit parameters
113 $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 $prototype->in_place_editor_stylesheet
120 Returns the in_place_editor stylesheet.
121 $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 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 Required options are:
131 "url": Specifies the URL to be used in the AJAX call.
133 Addtional options are:
135 "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 "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 "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 <% $c->prototype->define_javascript_functions %>
151 <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 <span id="acomp_auto_complete"></span><br/>
162 <% $c->prototype->auto_complete_field( 'acomp', { url => '/autocomplete', indicator => 'acomp_stat' } ) %>
164 while autocomplete is running.
166 "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 "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 "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 "on_show": Like on_hide, only now the expression is called then the
182 div is shown.
183 "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 $prototype->auto_complete_result(\@items, $fieldname, [$phrase])
189 Returns a list, to communcate with the Autocompleter.
190 Here's an example for Catalyst:
192 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 $prototype->text_field_with_auto_complete($method, [\%tag_options],
200 [\%completion_options])
201 Wrapper for text_field with added Ajax autocompletion
202 functionality.
203 In your controller, you'll need to define an action called
205 auto_complete_for_object_method to respond the AJAX calls,
206 $prototype->auto_complete_stylesheet
208 Returns the auto_complete stylesheet.
209 $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 $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 $prototype->define_javascript_functions
223 Returns the library of JavaScript functions and objects, in a
224 script block.
225 Notes for Catalyst users:
227 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 $prototype->draggable_element( $element_id, \%options )
232 Makes the element with the DOM ID specified by "element_id"
233 draggable.
234 Example:
236 $prototype->draggable_element( 'my_image', { revert => 'true' } );
238 The available options are:
240 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 revert
249 Default: false. If set to true, the element returns to its
250 original position when the drags ends.
251 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 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 'function (element) { // do something with dragged element }'
265 See http://script.aculo.us for more documentation.
267 $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 And make an AJAX call.
273 By default, the action called gets the DOM ID of the element as
275 parameter.
276 Example:
278 $prototype->drop_receiving_element(
279 'my_cart', { url => 'http://foo.bar/add' } );
280 Required options are:
282 url The URL for the AJAX call.
284 Additional options are:
286 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 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 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 Additionally, the following JavaScript callback functions can
305 be used in the option parameter:
306 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 'function (draggable, droppable, pcnt) { // do something }'
316 See http://script.aculo.us for more documentation.
318 $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 $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 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 The options for specifying the target with "url" and defining
334 callbacks are the same as "link_to_remote".
335 $prototype->javascript_tag( $content, \%html_options )
337 Returns a javascript block with opening tag, content and ending
338 tag.
339 $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 Examples:
345 $prototype->link_to_function( "Greeting", "alert('Hello world!') )
347 $prototype->link_to_function( '<img src="really.png"/>', 'do_delete()', { entities => '' } )
348 $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 The result of that request can then be inserted into a DOM object
354 whose id can be specified with options->{update}.
355 Examples:
357 $prototype->link_to_remote( 'Delete', {
359 update => 'posts',
360 url => 'http://localhost/posts/'
361 } )
362 $prototype->link_to_remote( '<img src="refresh.png"/>', {
364 update => 'emails',
365 url => 'http://localhost/refresh/'
366 } )
367 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 Example:
373 $prototype->link_to_remote( 'count', {
375 url => 'http://localhost/count/',
376 complete => 'doStuff(request)'
377 } )
378 The callbacks that may be specified are:
380 "loading": Called when the remote document is being loaded with
382 data by the browser.
383 "loaded": Called when the browser has finished loading the remote
385 document.
386 "interactive": Called when the user can interact with the remote
388 document, even though it has not finished loading.
389 "complete": Called when the XMLHttpRequest is complete.
391 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 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 "confirm": Adds confirmation dialog.
401 "condition": Perform remote request conditionally by this
403 expression. Use this to describe browser-side conditions when
404 request should not be initiated.
405 "before": Called before request is initiated.
407 "after": Called immediately after request was initiated and before
409 "loading".
410 $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 Required options are:
416 "frequency": The frequency (in seconds) at which changes to this
418 field will be detected.
419 "url": url to be called when field content has changed.
421 Additional options are:
423 "update": Specifies the DOM ID of the element whose innerHTML
425 should be updated with the XMLHttpRequest response text.
426 "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 Additionally, you may specify any of the options documented in
432 "link_to_remote".
433 Example TT2 template in Catalyst:
435 [% 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 $prototype->observe_form( $id, \%options )
448 Like "observe_field", but operates on an entire form identified by
449 the DOM ID $id.
450 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 $prototype->periodically_call_remote( \%options )
456 Periodically calls the specified url $options->{url} every
457 $options->{frequency} seconds (default is 10).
458 Usually used to update a specified div $options->{update} with the
460 results of the remote call.
461 The options for specifying the target with "url" and defining
463 callbacks is the same as "link_to_remote".
464 $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 Example:
472 $prototype->sortable_element( 'my_list', { url =>
473 'http://foo.bar/baz' } );
474 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 You can change the behaviour with various options, see
480 http://script.aculo.us for more documentation.
481 $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 "options" argument is the same as in "form_remote_tag"
488 $prototype->tag( $name, \%options, $starttag );
490 Returns a opening tag.
491 $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 "content": The content to use for updating. Can be left out if
497 using block, see example.
498 "action": Valid options are "update" (assumed by default), :empty,
500 :remove
501 "position": If the :action is :update, you can optionally specify
503 one of the following positions: :before, :top, :bottom, :after.
504 Example:
506 $prototype->javascript_tag(
507 $prototype->update_element_function(
508 'products', { position => 'bottom', content => '<p>New
509 product!</p>'
510 ) );
511 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 Example:
517 # View
518 $prototype->form_remote_tag( {
519 url => { "http://foo.bar/buy" },
520 complete => $prototype->evaluate_remote_response
521 } );
522 # 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 $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 $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
545 Catalyst::Plugin::Prototype, Catalyst. <http://prototype.conio.net/>
546
548 Sascha Kiefer, "esskar@cpan.org" Sebastian Riedel, "sri@oook.de" Marcus
549 Ramberg, "mramberg@cpan.org"
550 Built around Prototype by Sam Stephenson. Much code is ported from
552 Ruby on Rails javascript helpers.
553
555 Drew Taylor, Leon Brocard, Andreas Marienborg
556
558 This library is free software. You can redistribute it and/or modify it
559 under the same terms as perl itself.
560
562 Hey! The above document had some coding errors, which are explained
563 below:
564 Around line 111:
566 Non-ASCII character seen before =encoding in '‘cols’'. Assuming
567 CP1252
568perl v5.28.1 2006-09-22 HTML::Prototype(3)