5 use parent qw(Rose::Object);
10 use Rose::Object::MakeMethods::Generic
12 scalar => [ qw(controller) ],
13 'scalar --get_set_init' => [ qw(_actions _flash _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 reinit_widgets => 0, # kivi.reinit_widgets()
119 run => -1, # kivi.run(<TARGET>, <ARGS>)
120 run_once_for => 3, # kivi.run_once_for(<TARGET>, <ARGS>)
122 scroll_into_view => 1, # $(<TARGET>)[0].scrollIntoView()
128 my ($self, @args) = @_;
130 my $method = $AUTOLOAD;
132 return if $method eq 'DESTROY';
133 return $self->action($method, @args);
137 my ($self, $method, @args) = @_;
139 $method = (delete($self->{_prefix}) || '') . $method;
140 my $num_args = $supported_methods{$method};
142 croak "Unsupported jQuery action: $method" unless defined $num_args;
145 croak "Parameter count mismatch for $method(actual: " . scalar(@args) . " wanted: $num_args)" if scalar(@args) != $num_args;
148 croak "Parameter count mismatch for $method(actual: " . scalar(@args) . " wanted at least: $num_args)" if scalar(@args) < $num_args;
149 $num_args = scalar @args;
152 foreach my $idx (0..$num_args - 1) {
153 # Force flattening from SL::Presenter::EscapedText and trim leading whitespace for scalars
154 $args[$idx] = "" . $args[$idx] if ref($args[$idx]) eq 'SL::Presenter::EscapedText';
157 push @{ $self->_actions }, [ $method, @args ];
163 my ($self, $condition, @args) = @_;
165 return $condition ? $self->action(@args) : $self;
183 return SL::JSON::to_json({ error => $self->_error }) if $self->_error;
184 return SL::JSON::to_json({ eval_actions => $self->_actions });
189 return $self->_actions;
193 my ($self, $controller) = @_;
194 $controller ||= $self->controller;
195 $self->reinit_widgets if $::request->presenter->need_reinit_widgets;
196 return $controller->render(\$self->to_json, { type => 'json' });
201 $self->{_prefix} = 'jstree:';
207 $self->{_prefix} = 'dialog:';
213 $self->{_prefix} = 'ckeditor:';
218 my ($self, $type, @messages) = @_;
220 my $message = join ' ', grep { $_ } @messages;
222 if (!$self->_flash->{$type}) {
223 $self->_flash->{$type} = [ 'flash', $type, $message ];
224 push @{ $self->_actions }, $self->_flash->{$type};
226 $self->_flash->{$type}->[-1] .= ' ' . $message;
233 my ($self, @messages) = @_;
235 $self->_error(join ' ', grep { $_ } ($self->_error, @messages));
249 SL::ClientJS - Easy programmatic client-side JavaScript generation
254 First some JavaScript code:
256 // In the client generate an AJAX request whose 'success' handler
257 // calls "eval_json_result(data)":
259 action: "SomeController/the_action",
260 id: $('#some_input_field').val()
262 $.post("controller.pl", data, eval_json_result);
266 # In the controller itself. First, make sure that the "client_js.js"
267 # is loaded. This must be done when the whole side is loaded, so
268 # it's not in the action called by the AJAX request shown above.
269 $::request->layout->use_javascript('client_js.js');
271 # Now in that action called via AJAX:
272 sub action_the_action {
275 # Create a new client-side JS object and do stuff with it!
276 my $js = SL::ClientJS->new(controller => $self);
278 # Show some element on the page:
279 $js->show('#usually_hidden');
281 # Set to hidden inputs. Yes, calls can be chained!
282 $js->val('#hidden_id', $self->new_id)
283 ->val('#other_type', 'Unicorn');
285 # Replace some HTML code:
286 my $html = $self->render('SomeController/the_action', { output => 0 });
287 $js->html('#id_with_new_content', $html);
289 # Operations on a jstree: rename a node and select it
290 my $text_block = SL::DB::RequirementSpecTextBlock->new(id => 4711)->load;
291 $js->jstree->rename_node('#tb-' . $text_block->id, $text_block->title)
292 ->jstree->select_node('#tb-' . $text_block->id);
294 # Close a popup opened by kivi.popup_dialog():
295 $js->dialog->close('#jqueryui_popup_dialog');
297 # Finally render the JSON response:
300 # Rendering can also be chained, e.g.
301 $js->html('#selector', $html)
307 This module enables the generation of jQuery-using JavaScript code on
308 the server side. That code is then evaluated in a safe way on the
311 The workflow is usally that the client creates an AJAX request, the
312 server creates some actions and sends them back, and the client then
313 implements each of these actions.
315 There are three things that need to be done for this to work:
319 =item 1. The "client_js.js" has to be loaded before the AJAX request is started.
321 =item 2. The client code needs to call C<kivi.eval_json_result()> with the result returned from the server.
323 =item 3. The server must use this module.
327 The functions called on the client side are mostly jQuery
328 functions. Other functionality may be added later.
330 Note that L<SL::Controller/render> is aware of this module which saves
331 you some boilerplate. The following two calls are equivalent:
333 $controller->render($client_js);
334 $controller->render(\$client_js->to_json, { type => 'json' });
336 =head1 FUNCTIONS NOT PASSED TO THE CLIENT SIDE
342 Returns the actions gathered so far as an array reference. Each
343 element is an array reference containing at least two items: the
344 function's name and what it is called on. Additional array elements
345 are the function parameters.
349 Returns the actions gathered so far as a JSON string ready to be sent
352 =item C<render [$controller]>
354 Renders C<$self> via the controller. Useful for chaining. Equivalent
357 $controller->render(\$self->to_json, { type => 'json' });
359 The controller instance to use can be set during object creation (see
360 synopsis) or as an argument to C<render>.
364 Tells C<$self> that the next action is to be called on a jQuery UI
365 dialog instance, e.g. one opened by C<kivi.popup_dialog()>. For
368 $js->dialog->close('#jqueryui_popup_dialog');
372 Tells C<$self> that the next action is to be called on a jstree
373 instance. For example:
375 $js->jstree->rename_node('tb-' . $text_block->id, $text_block->title);
379 =head1 FUNCTIONS EVALUATED ON THE CLIENT SIDE
381 =head2 GENERIC FUNCTION
383 All of the following functions can be invoked in two ways: either by
384 calling the function name directly on C<$self> or by calling
385 L</action> with the function name as the first parameter. Therefore
386 the following two calls are identical:
388 $js->insertAfter($html, '#some-id');
389 $js->action('insertAfter', $html, '#some-id');
391 The second form, calling L</action>, is more to type but can be useful
392 in situations in which you have to call one of two functions depending
393 on context. For example, when you want to insert new code in a
394 list. If the list is empty you might have to use C<appendTo>, if it
395 isn't you might have to use C<insertAfter>. Example:
397 my $html = $self->render(...);
398 $js->action($list_is_empty ? 'appendTo' : 'insertAfter', $html, '#text-block-' . ($list_is_empty ? 'list' : $self->text_block->id));
402 my $html = $self->render(...);
403 if ($list_is_empty) {
404 $js->appendTo($html, '#text-block-list');
406 $js->insertAfter($html, '#text-block-' . $self->text_block->id);
409 The first variation is obviously better suited for chaining.
413 =item C<action $method, @args>
415 Call the function with the name C<$method> on C<$self> with arguments
416 C<@args>. Returns the return value of the actual function
417 called. Useful for chaining (see above).
419 =item C<action_if $condition, $method, @args>
421 Call the function with the name C<$method> on C<$self> with arguments
422 C<@args> if C<$condition> is trueish. Does nothing otherwise.
424 Returns the return value of the actual function called if
425 C<$condition> is trueish and C<$self> otherwise. Useful for chaining
428 This function is equivalent to the following:
431 $obj->$method(@args);
434 But it is easier to integrate into a method call chain, e.g.:
436 $js->html('#content', $html)
437 ->action_if($item->is_flagged, 'toggleClass', '#marker', 'flagged')
442 =head2 ADDITIONAL FUNCTIONS
446 =item C<flash $type, $message>
448 Display a C<$message> in the flash of type C<$type>. Multiple calls of
449 C<flash> on the same C<$self> will be merged by type.
451 On the client side the flashes of all types will be cleared after each
452 successful ClientJS call that did not end with C<$js-E<gt>error(...)>.
454 =item C<error $message>
456 Causes L<to_json> (and therefore L<render>) to output a JSON object
457 that only contains an C<error> field set to this C<$message>. The
458 client will then show the message in the 'error' flash.
460 The messages of multiple calls of C<error> on the same C<$self> will
463 =item C<redirect_to $url>
465 Redirects the browser window to the new URL by setting the JavaScript
466 property C<window.location.href>. Note that
467 L<SL::Controller::Base/redirect_to> is AJAX aware and uses this
468 function if the current request is an AJAX request as determined by
469 L<SL::Request/is_ajax>.
473 =head2 KIVITENDO FUNCTIONS
475 The following functions from the C<kivi> namespace are supported:
479 =item Displaying stuff
481 C<flash> (don't call directly, use L</flash> instead)
483 =item Running functions
485 C<run>, C<run_once_for>
493 =head2 JQUERY FUNCTIONS
495 The following jQuery functions are supported:
501 C<hide>, C<show>, C<toggle>
503 =item DOM insertion, around
505 C<unwrap>, C<wrap>, C<wrapAll>, C<wrapInner>
507 =item DOM insertion, inside
509 C<append>, C<appendTo>, C<html>, C<prepend>, C<prependTo>, C<text>
511 =item DOM insertion, outside
513 C<after>, C<before>, C<insertAfter>, C<insertBefore>
519 =item DOM replacement
521 C<replaceAll>, C<replaceWith>
523 =item General attributes
525 C<attr>, C<prop>, C<removeAttr>, C<removeProp>, C<val>
527 =item Class attributes
529 C<addClass>, C<removeClass>, C<toggleClass>
533 C<data>, C<removeData>
539 =item Generic Event Handlers
541 C<on>, C<off>, C<one>
543 These attach/detach event listeners to specific selectors. The first
544 argument is the selector, the second the name of the events and the
545 third argument is the name of the handler function. That function must
546 already exist when the handler is added.
550 =head2 JQUERY POPUP DIALOG PLUGIN
552 Supported functions of the C<popup dialog> plugin to jQuery. They are
553 invoked by first calling C<dialog> in the ClientJS instance and then
556 $js->dialog->close(...);
560 =item Closing and removing the popup
566 =head2 AJAXFORM JQUERY PLUGIN
568 The following functions of the C<ajaxForm> plugin to jQuery are
573 =item All functions by the generic accessor function:
579 =head2 JSTREE JQUERY PLUGIN
581 Supported functions of the C<jstree> plugin to jQuery. They are
582 invoked by first calling C<jstree> in the ClientJS instance and then
585 $js->jstree->open_node(...);
589 =item Operations on the whole tree
593 =item Opening and closing nodes
595 C<open_node>, C<close_node>, C<toggle_node>, C<open_all>,
596 C<close_all>, C<save_opened>, C<reopen>
598 =item Modifying nodes
600 C<rename_node>, C<delete_node>, C<move_node>
602 =item Selecting nodes (from the 'ui' jstree plugin)
604 C<select_node>, C<deselect_node>, C<deselect_all>
608 =head1 ADDING SUPPORT FOR ADDITIONAL FUNCTIONS
610 In order not having to maintain two files (this one and
611 C<js/client_js.js>) there's a script that can parse this file's
612 C<%supported_methods> definition and generate the file
613 C<js/client_js.js> accordingly. The steps are:
617 =item 1. Add lines in this file to the C<%supported_methods> hash. The
618 key is the function name and the value is the number of expected
619 parameters. The value can be negative to indicate that the function
620 takes at least the absolute of this value as parameters and optionally
621 more. In such a case the C<E<lt>ARGSE<gt>> format expands to an actual
622 array (and the individual elements if the value is positive>.
624 =item 2. Run C<scripts/generate_client_js_actions.pl>. It will
625 generate C<js/client_js.js> automatically.
627 =item 3. Reload the files in your browser (cleaning its cache can also
632 The template file used for generated C<js/client_js.js> is
633 C<scripts/generate_client_js_actions.tpl>.
641 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>