5 use parent qw(Rose::Object);
10 use Rose::Object::MakeMethods::Generic
13 'scalar --get_set_init' => [ qw(controller _actions _flash _flash_detail _error) ],
16 my %supported_methods = (
24 # DOM insertion, around
30 # DOM insertion, inside
38 # DOM insertion, outside
69 focus => 1, # kivi.set_focus(<TARGET>)
71 # Generic Event Handling ## pattern: $(<TARGET>).<FUNCTION>(<ARG1>, kivi.get_function_by_name(<ARG2>))
76 # ## jQuery UI dialog plugin ## pattern: $(<TARGET>).dialog('<FUNCTION>')
78 # Opening and closing and closing a popup
79 'dialog:open' => 1, # kivi.popup_dialog(<TARGET>)
82 # ## jQuery Form plugin ##
83 'ajaxForm' => 1, # pattern: $(<TARGET>).ajaxForm({ success: eval_json_result })
85 # ## jstree plugin ## pattern: $.jstree._reference($(<TARGET>)).<FUNCTION>(<ARGS>)
87 # Operations on the whole tree
91 # Opening and closing nodes
92 'jstree:open_node' => 2,
93 'jstree:open_all' => 2,
94 'jstree:close_node' => 2,
95 'jstree:close_all' => 2,
96 'jstree:toggle_node' => 2,
97 'jstree:save_opened' => 1,
101 'jstree:create_node' => 4,
102 'jstree:rename_node' => 3,
103 'jstree:delete_node' => 2,
104 'jstree:move_node' => 5,
106 # Selecting nodes (from the 'ui' plugin to jstree)
107 'jstree:select_node' => 2, # $.jstree._reference($(<TARGET>)).<FUNCTION>(<ARGS>, true)
108 'jstree:deselect_node' => 2,
109 'jstree:deselect_all' => 1,
111 # ## ckeditor stuff ##
112 'focus_ckeditor' => 1, # kivi.focus_ckeditor_when_ready(<TARGET>)
115 redirect_to => 1, # window.location.href = <TARGET>
117 flash => 2, # kivi.display_flash(<TARGET>, <ARGS>)
118 flash_detail => 2, # kivi.display_flash_detail(<TARGET>, <ARGS>)
119 clear_flash => 2, # kivi.display_flash_detail(<TARGET>, <ARGS>)
120 reinit_widgets => 0, # kivi.reinit_widgets()
121 run => -1, # kivi.run(<TARGET>, <ARGS>)
122 run_once_for => 3, # kivi.run_once_for(<TARGET>, <ARGS>)
124 scroll_into_view => 1, # $(<TARGET>)[0].scrollIntoView()
127 my %trim_target_for = map { ($_ => 1) } qw(insertAfter insertBefore appendTo prependTo);
132 my ($self, @args) = @_;
134 my $method = $AUTOLOAD;
136 return if $method eq 'DESTROY';
137 return $self->action($method, @args);
141 my ($self, $method, @args) = @_;
143 $method = (delete($self->{_prefix}) || '') . $method;
144 my $num_args = $supported_methods{$method};
146 croak "Unsupported jQuery action: $method" unless defined $num_args;
149 croak "Parameter count mismatch for $method(actual: " . scalar(@args) . " wanted: $num_args)" if scalar(@args) != $num_args;
152 croak "Parameter count mismatch for $method(actual: " . scalar(@args) . " wanted at least: $num_args)" if scalar(@args) < $num_args;
153 $num_args = scalar @args;
156 foreach my $idx (0..$num_args - 1) {
157 # Force flattening from SL::Presenter::EscapedText.
158 $args[$idx] = "" . $args[$idx] if ref($args[$idx]) eq 'SL::Presenter::EscapedText';
161 # Trim leading whitespaces for certain jQuery functions that operate
162 # on HTML code: $("<p>test</p>").appendTo('#some-id'). jQuery croaks
163 # on leading whitespaces, e.g. on $(" <p>test</p>").
164 $args[0] =~ s{^\s+}{} if $trim_target_for{$method};
166 push @{ $self->_actions }, [ $method, @args ];
172 my ($self, $condition, @args) = @_;
174 return $condition ? $self->action(@args) : $self;
185 sub init__flash_detail {
196 return SL::JSON::to_json({ error => $self->_error }) if $self->_error;
197 return SL::JSON::to_json({ eval_actions => $self->_actions });
202 return $self->_actions;
206 my ($self, $controller) = @_;
207 $controller ||= $self->controller;
208 $self->reinit_widgets if $::request->presenter->need_reinit_widgets;
209 return $controller->render(\$self->to_json, { type => 'json' });
214 $self->{_prefix} = 'jstree:';
220 $self->{_prefix} = 'dialog:';
226 $self->{_prefix} = 'ckeditor:';
231 my ($self, $type, @messages) = @_;
233 my $message = join ' ', grep { $_ } @messages;
235 if (!$self->_flash->{$type}) {
236 $self->_flash->{$type} = [ 'flash', $type, $message ];
237 push @{ $self->_actions }, $self->_flash->{$type};
239 $self->_flash->{$type}->[-1] .= ' ' . $message;
246 my ($self, $type, @messages) = @_;
248 my $message = join '<br>', grep { $_ } @messages;
250 if (!$self->_flash_detail->{$type}) {
251 $self->_flash_detail->{$type} = [ 'flash_detail', $type, $message ];
252 push @{ $self->_actions }, $self->_flash_detail->{$type};
254 $self->_flash_detail->{$type}->[-1] .= ' ' . $message;
261 my ($self, @messages) = @_;
263 $self->_error(join ' ', grep { $_ } ($self->_error, @messages));
268 sub init_controller {
270 require SL::Controller::Base;
271 SL::Controller::Base->new;
283 SL::ClientJS - Easy programmatic client-side JavaScript generation
288 First some JavaScript code:
290 // In the client generate an AJAX request whose 'success' handler
291 // calls "eval_json_result(data)":
293 action: "SomeController/the_action",
294 id: $('#some_input_field').val()
296 $.post("controller.pl", data, eval_json_result);
300 # In the controller itself. First, make sure that the "client_js.js"
301 # is loaded. This must be done when the whole side is loaded, so
302 # it's not in the action called by the AJAX request shown above.
303 $::request->layout->use_javascript('client_js.js');
305 # Now in that action called via AJAX:
306 sub action_the_action {
309 # Create a new client-side JS object and do stuff with it!
310 my $js = SL::ClientJS->new(controller => $self);
312 # Show some element on the page:
313 $js->show('#usually_hidden');
315 # Set to hidden inputs. Yes, calls can be chained!
316 $js->val('#hidden_id', $self->new_id)
317 ->val('#other_type', 'Unicorn');
319 # Replace some HTML code:
320 my $html = $self->render('SomeController/the_action', { output => 0 });
321 $js->html('#id_with_new_content', $html);
323 # Operations on a jstree: rename a node and select it
324 my $text_block = SL::DB::RequirementSpecTextBlock->new(id => 4711)->load;
325 $js->jstree->rename_node('#tb-' . $text_block->id, $text_block->title)
326 ->jstree->select_node('#tb-' . $text_block->id);
328 # Close a popup opened by kivi.popup_dialog():
329 $js->dialog->close('#jqueryui_popup_dialog');
331 # Finally render the JSON response:
334 # Rendering can also be chained, e.g.
335 $js->html('#selector', $html)
341 This module enables the generation of jQuery-using JavaScript code on
342 the server side. That code is then evaluated in a safe way on the
345 The workflow is usally that the client creates an AJAX request, the
346 server creates some actions and sends them back, and the client then
347 implements each of these actions.
349 There are three things that need to be done for this to work:
353 =item 1. The "client_js.js" has to be loaded before the AJAX request is started.
355 =item 2. The client code needs to call C<kivi.eval_json_result()> with the result returned from the server.
357 =item 3. The server must use this module.
361 The functions called on the client side are mostly jQuery
362 functions. Other functionality may be added later.
364 Note that L<SL::Controller/render> is aware of this module which saves
365 you some boilerplate. The following two calls are equivalent:
367 $controller->render($client_js);
368 $controller->render(\$client_js->to_json, { type => 'json' });
370 =head1 FUNCTIONS NOT PASSED TO THE CLIENT SIDE
376 Returns the actions gathered so far as an array reference. Each
377 element is an array reference containing at least two items: the
378 function's name and what it is called on. Additional array elements
379 are the function parameters.
383 Returns the actions gathered so far as a JSON string ready to be sent
386 =item C<render [$controller]>
388 Renders C<$self> via the controller. Useful for chaining. Equivalent
391 $controller->render(\$self->to_json, { type => 'json' });
393 The controller instance to use can be set during object creation (see
394 synopsis) or as an argument to C<render>.
398 Tells C<$self> that the next action is to be called on a jQuery UI
399 dialog instance, e.g. one opened by C<kivi.popup_dialog()>. For
402 $js->dialog->close('#jqueryui_popup_dialog');
406 Tells C<$self> that the next action is to be called on a jstree
407 instance. For example:
409 $js->jstree->rename_node('tb-' . $text_block->id, $text_block->title);
413 =head1 FUNCTIONS EVALUATED ON THE CLIENT SIDE
415 =head2 GENERIC FUNCTION
417 All of the following functions can be invoked in two ways: either by
418 calling the function name directly on C<$self> or by calling
419 L</action> with the function name as the first parameter. Therefore
420 the following two calls are identical:
422 $js->insertAfter($html, '#some-id');
423 $js->action('insertAfter', $html, '#some-id');
425 The second form, calling L</action>, is more to type but can be useful
426 in situations in which you have to call one of two functions depending
427 on context. For example, when you want to insert new code in a
428 list. If the list is empty you might have to use C<appendTo>, if it
429 isn't you might have to use C<insertAfter>. Example:
431 my $html = $self->render(...);
432 $js->action($list_is_empty ? 'appendTo' : 'insertAfter', $html, '#text-block-' . ($list_is_empty ? 'list' : $self->text_block->id));
436 my $html = $self->render(...);
437 if ($list_is_empty) {
438 $js->appendTo($html, '#text-block-list');
440 $js->insertAfter($html, '#text-block-' . $self->text_block->id);
443 The first variation is obviously better suited for chaining.
447 =item C<action $method, @args>
449 Call the function with the name C<$method> on C<$self> with arguments
450 C<@args>. Returns the return value of the actual function
451 called. Useful for chaining (see above).
453 =item C<action_if $condition, $method, @args>
455 Call the function with the name C<$method> on C<$self> with arguments
456 C<@args> if C<$condition> is trueish. Does nothing otherwise.
458 Returns the return value of the actual function called if
459 C<$condition> is trueish and C<$self> otherwise. Useful for chaining
462 This function is equivalent to the following:
465 $obj->$method(@args);
468 But it is easier to integrate into a method call chain, e.g.:
470 $js->html('#content', $html)
471 ->action_if($item->is_flagged, 'toggleClass', '#marker', 'flagged')
476 =head2 ADDITIONAL FUNCTIONS
480 =item C<flash $type, $message>
482 Display a C<$message> in the flash of type C<$type>. Multiple calls of
483 C<flash> on the same C<$self> will be merged by type.
485 On the client side the flashes of all types will be cleared after each
486 successful ClientJS call that did not end with C<$js-E<gt>error(...)>.
488 =item C<error $message>
490 Causes L<to_json> (and therefore L<render>) to output a JSON object
491 that only contains an C<error> field set to this C<$message>. The
492 client will then show the message in the 'error' flash.
494 The messages of multiple calls of C<error> on the same C<$self> will
497 =item C<redirect_to $url>
499 Redirects the browser window to the new URL by setting the JavaScript
500 property C<window.location.href>. Note that
501 L<SL::Controller::Base/redirect_to> is AJAX aware and uses this
502 function if the current request is an AJAX request as determined by
503 L<SL::Request/is_ajax>.
507 =head2 KIVITENDO FUNCTIONS
509 The following functions from the C<kivi> namespace are supported:
513 =item Displaying stuff
515 C<flash> (don't call directly, use L</flash> instead)
517 =item Running functions
519 C<run>, C<run_once_for>
527 =head2 JQUERY FUNCTIONS
529 The following jQuery functions are supported:
535 C<hide>, C<show>, C<toggle>
537 =item DOM insertion, around
539 C<unwrap>, C<wrap>, C<wrapAll>, C<wrapInner>
541 =item DOM insertion, inside
543 C<append>, C<appendTo>, C<html>, C<prepend>, C<prependTo>, C<text>
545 =item DOM insertion, outside
547 C<after>, C<before>, C<insertAfter>, C<insertBefore>
553 =item DOM replacement
555 C<replaceAll>, C<replaceWith>
557 =item General attributes
559 C<attr>, C<prop>, C<removeAttr>, C<removeProp>, C<val>
561 =item Class attributes
563 C<addClass>, C<removeClass>, C<toggleClass>
567 C<data>, C<removeData>
573 =item Generic Event Handlers
575 C<on>, C<off>, C<one>
577 These attach/detach event listeners to specific selectors. The first
578 argument is the selector, the second the name of the events and the
579 third argument is the name of the handler function. That function must
580 already exist when the handler is added.
584 =head2 JQUERY POPUP DIALOG PLUGIN
586 Supported functions of the C<popup dialog> plugin to jQuery. They are
587 invoked by first calling C<dialog> in the ClientJS instance and then
590 $js->dialog->close(...);
594 =item Closing and removing the popup
600 =head2 AJAXFORM JQUERY PLUGIN
602 The following functions of the C<ajaxForm> plugin to jQuery are
607 =item All functions by the generic accessor function:
613 =head2 JSTREE JQUERY PLUGIN
615 Supported functions of the C<jstree> plugin to jQuery. They are
616 invoked by first calling C<jstree> in the ClientJS instance and then
619 $js->jstree->open_node(...);
623 =item Operations on the whole tree
627 =item Opening and closing nodes
629 C<open_node>, C<close_node>, C<toggle_node>, C<open_all>,
630 C<close_all>, C<save_opened>, C<reopen>
632 =item Modifying nodes
634 C<rename_node>, C<delete_node>, C<move_node>
636 =item Selecting nodes (from the 'ui' jstree plugin)
638 C<select_node>, C<deselect_node>, C<deselect_all>
642 =head1 ADDING SUPPORT FOR ADDITIONAL FUNCTIONS
644 In order not having to maintain two files (this one and
645 C<js/client_js.js>) there's a script that can parse this file's
646 C<%supported_methods> definition and generate the file
647 C<js/client_js.js> accordingly. The steps are:
651 =item 1. Add lines in this file to the C<%supported_methods> hash. The
652 key is the function name and the value is the number of expected
653 parameters. The value can be negative to indicate that the function
654 takes at least the absolute of this value as parameters and optionally
655 more. In such a case the C<E<lt>ARGSE<gt>> format expands to an actual
656 array (and the individual elements if the value is positive>.
658 =item 2. Run C<scripts/generate_client_js_actions.pl>. It will
659 generate C<js/client_js.js> automatically.
661 =item 3. Reload the files in your browser (cleaning its cache can also
666 The template file used for generated C<js/client_js.js> is
667 C<scripts/generate_client_js_actions.tpl>.
675 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>