Pflichtenheftaufträge: Pauschalpos. in Ang./Auftr. erstellen können
[kivitendo-erp.git] / SL / ClientJS.pm
1 package SL::ClientJS;
2
3 use strict;
4
5 use parent qw(Rose::Object);
6
7 use Carp;
8 use SL::JSON ();
9
10 use Rose::Object::MakeMethods::Generic
11 (
12   scalar                  => [ qw(controller) ],
13   'scalar --get_set_init' => [ qw(_actions _flash _error) ],
14 );
15
16 my %supported_methods = (
17   # ## jQuery basics ##
18
19   # Basic effects
20   hide         => 1,
21   show         => 1,
22   toggle       => 1,
23
24   # DOM insertion, around
25   unwrap       => 1,
26   wrap         => 2,
27   wrapAll      => 2,
28   wrapInner    => 2,
29
30   # DOM insertion, inside
31   append       => 2,
32   appendTo     => 2,
33   html         => 2,
34   prepend      => 2,
35   prependTo    => 2,
36   text         => 2,
37
38   # DOM insertion, outside
39   after        => 2,
40   before       => 2,
41   insertAfter  => 2,
42   insertBefore => 2,
43
44   # DOM removal
45   empty        => 1,
46   remove       => 1,
47
48   # DOM replacement
49   replaceAll   => 2,
50   replaceWith  => 2,
51
52   # General attributes
53   attr         => 3,
54   prop         => 3,
55   removeAttr   => 2,
56   removeProp   => 2,
57   val          => 2,
58
59   # Class attribute
60   addClass     => 2,
61   removeClass  => 2,
62   toggleClass  => 2,
63
64   # Data storage
65   data         => 3,
66   removeData   => 2,
67
68   # Form Events
69   focus        => 1, # kivi.set_focus(<TARGET>)
70
71   # Generic Event Handling ## pattern: $(<TARGET>).<FUNCTION>(<ARG1>, kivi.get_function_by_name(<ARG2>))
72   on           => 3,
73   off          => 3,
74   one          => 3,
75
76   # ## jQuery UI dialog plugin ## pattern: $(<TARGET>).dialog('<FUNCTION>')
77
78   # Closing and removing the popup
79   'dialog:close'         => 1,
80
81   # ## jQuery Form plugin ##
82   'ajaxForm'             => 1, # pattern: $(<TARGET>).ajaxForm({ success: eval_json_result })
83
84   # ## jstree plugin ## pattern: $.jstree._reference($(<TARGET>)).<FUNCTION>(<ARGS>)
85
86   # Operations on the whole tree
87   'jstree:lock'          => 1,
88   'jstree:unlock'        => 1,
89
90   # Opening and closing nodes
91   'jstree:open_node'     => 2,
92   'jstree:open_all'      => 2,
93   'jstree:close_node'    => 2,
94   'jstree:close_all'     => 2,
95   'jstree:toggle_node'   => 2,
96   'jstree:save_opened'   => 1,
97   'jstree:reopen'        => 1,
98
99   # Modifying nodes
100   'jstree:create_node'   => 4,
101   'jstree:rename_node'   => 3,
102   'jstree:delete_node'   => 2,
103   'jstree:move_node'     => 5,
104
105   # Selecting nodes (from the 'ui' plugin to jstree)
106   'jstree:select_node'   => 2,  # $.jstree._reference($(<TARGET>)).<FUNCTION>(<ARGS>, true)
107   'jstree:deselect_node' => 2,
108   'jstree:deselect_all'  => 1,
109
110   # ## ckeditor stuff ##
111   'focus_ckeditor'       => 1,  # kivi.focus_ckeditor_when_ready(<TARGET>)
112
113   # ## other stuff ##
114   redirect_to            => 1,  # window.location.href = <TARGET>
115
116   flash                  => 2,  # kivi.display_flash(<TARGET>, <ARGS>)
117   reinit_widgets         => 0,  # kivi.reinit_widgets()
118   run                    => -1, # kivi.run(<TARGET>, <ARGS>)
119   run_once_for           => 3,  # kivi.run_once_for(<TARGET>, <ARGS>)
120 );
121
122 sub AUTOLOAD {
123   our $AUTOLOAD;
124
125   my ($self, @args) = @_;
126
127   my $method        =  $AUTOLOAD;
128   $method           =~ s/.*:://;
129   return if $method eq 'DESTROY';
130   return $self->action($method, @args);
131 }
132
133 sub action {
134   my ($self, $method, @args) = @_;
135
136   $method      =  (delete($self->{_prefix}) || '') . $method;
137   my $num_args =  $supported_methods{$method};
138
139   croak "Unsupported jQuery action: $method"                                                    unless defined $num_args;
140
141   if ($num_args > 0) {
142     croak "Parameter count mismatch for $method(actual: " . scalar(@args) . " wanted: $num_args)" if scalar(@args) != $num_args;
143   } else {
144     $num_args *= -1;
145     croak "Parameter count mismatch for $method(actual: " . scalar(@args) . " wanted at least: $num_args)" if scalar(@args) < $num_args;
146     $num_args  = scalar @args;
147   }
148
149   foreach my $idx (0..$num_args - 1) {
150     # Force flattening from SL::Presenter::EscapedText and trim leading whitespace for scalars
151     $args[$idx] =  "" . $args[$idx] if  ref($args[$idx]) eq 'SL::Presenter::EscapedText';
152     $args[$idx] =~ s/^\s+//         if !ref($args[$idx]);
153   }
154
155   push @{ $self->_actions }, [ $method, @args ];
156
157   return $self;
158 }
159
160 sub action_if {
161   my ($self, $condition, @args) = @_;
162
163   return $condition ? $self->action(@args) : $self;
164 }
165
166 sub init__actions {
167   return [];
168 }
169
170 sub init__flash {
171   return {};
172 }
173
174 sub init__error {
175   return '';
176 }
177
178 sub to_json {
179   my ($self) = @_;
180
181   return SL::JSON::to_json({ error        => $self->_error   }) if $self->_error;
182   return SL::JSON::to_json({ eval_actions => $self->_actions });
183 }
184
185 sub to_array {
186   my ($self) = @_;
187   return $self->_actions;
188 }
189
190 sub render {
191   my ($self, $controller) = @_;
192   $controller ||= $self->controller;
193   $self->reinit_widgets if $::request->presenter->need_reinit_widgets;
194   return $controller->render(\$self->to_json, { type => 'json' });
195 }
196
197 sub jstree {
198   my ($self) = @_;
199   $self->{_prefix} = 'jstree:';
200   return $self;
201 }
202
203 sub dialog {
204   my ($self) = @_;
205   $self->{_prefix} = 'dialog:';
206   return $self;
207 }
208
209 sub ckeditor {
210   my ($self) = @_;
211   $self->{_prefix} = 'ckeditor:';
212   return $self;
213 }
214
215 sub flash {
216   my ($self, $type, @messages) = @_;
217
218   my $message = join ' ', grep { $_ } @messages;
219
220   if (!$self->_flash->{$type}) {
221     $self->_flash->{$type} = [ 'flash', $type, $message ];
222     push @{ $self->_actions }, $self->_flash->{$type};
223   } else {
224     $self->_flash->{$type}->[-1] .= ' ' . $message;
225   }
226
227   return $self;
228 }
229
230 sub error {
231   my ($self, @messages) = @_;
232
233   $self->_error(join ' ', grep { $_ } ($self->_error, @messages));
234
235   return $self;
236 }
237
238 1;
239 __END__
240
241 =pod
242
243 =encoding utf8
244
245 =head1 NAME
246
247 SL::ClientJS - Easy programmatic client-side JavaScript generation
248 with jQuery
249
250 =head1 SYNOPSIS
251
252 First some JavaScript code:
253
254   // In the client generate an AJAX request whose 'success' handler
255   // calls "eval_json_result(data)":
256   var data = {
257     action: "SomeController/the_action",
258     id:     $('#some_input_field').val()
259   };
260   $.post("controller.pl", data, eval_json_result);
261
262 Now some Perl code:
263
264   # In the controller itself. First, make sure that the "client_js.js"
265   # is loaded. This must be done when the whole side is loaded, so
266   # it's not in the action called by the AJAX request shown above.
267   $::request->layout->use_javascript('client_js.js');
268
269   # Now in that action called via AJAX:
270   sub action_the_action {
271     my ($self) = @_;
272
273     # Create a new client-side JS object and do stuff with it!
274     my $js = SL::ClientJS->new(controller => $self);
275
276     # Show some element on the page:
277     $js->show('#usually_hidden');
278
279     # Set to hidden inputs. Yes, calls can be chained!
280     $js->val('#hidden_id', $self->new_id)
281        ->val('#other_type', 'Unicorn');
282
283     # Replace some HTML code:
284     my $html = $self->render('SomeController/the_action', { output => 0 });
285     $js->html('#id_with_new_content', $html);
286
287     # Operations on a jstree: rename a node and select it
288     my $text_block = SL::DB::RequirementSpecTextBlock->new(id => 4711)->load;
289     $js->jstree->rename_node('#tb-' . $text_block->id, $text_block->title)
290        ->jstree->select_node('#tb-' . $text_block->id);
291
292     # Close a popup opened by kivi.popup_dialog():
293     $js->dialog->close('#jqueryui_popup_dialog');
294
295     # Finally render the JSON response:
296     $self->render($js);
297
298     # Rendering can also be chained, e.g.
299     $js->html('#selector', $html)
300        ->render;
301   }
302
303 =head1 OVERVIEW
304
305 This module enables the generation of jQuery-using JavaScript code on
306 the server side. That code is then evaluated in a safe way on the
307 client side.
308
309 The workflow is usally that the client creates an AJAX request, the
310 server creates some actions and sends them back, and the client then
311 implements each of these actions.
312
313 There are three things that need to be done for this to work:
314
315 =over 2
316
317 =item 1. The "client_js.js" has to be loaded before the AJAX request is started.
318
319 =item 2. The client code needs to call C<kivi.eval_json_result()> with the result returned from the server.
320
321 =item 3. The server must use this module.
322
323 =back
324
325 The functions called on the client side are mostly jQuery
326 functions. Other functionality may be added later.
327
328 Note that L<SL::Controller/render> is aware of this module which saves
329 you some boilerplate. The following two calls are equivalent:
330
331   $controller->render($client_js);
332   $controller->render(\$client_js->to_json, { type => 'json' });
333
334 =head1 FUNCTIONS NOT PASSED TO THE CLIENT SIDE
335
336 =over 4
337
338 =item C<to_array>
339
340 Returns the actions gathered so far as an array reference. Each
341 element is an array reference containing at least two items: the
342 function's name and what it is called on. Additional array elements
343 are the function parameters.
344
345 =item C<to_json>
346
347 Returns the actions gathered so far as a JSON string ready to be sent
348 to the client.
349
350 =item C<render [$controller]>
351
352 Renders C<$self> via the controller. Useful for chaining. Equivalent
353 to the following:
354
355   $controller->render(\$self->to_json, { type => 'json' });
356
357 The controller instance to use can be set during object creation (see
358 synopsis) or as an argument to C<render>.
359
360 =item C<dialog>
361
362 Tells C<$self> that the next action is to be called on a jQuery UI
363 dialog instance, e.g. one opened by C<kivi.popup_dialog()>. For
364 example:
365
366   $js->dialog->close('#jqueryui_popup_dialog');
367
368 =item C<jstree>
369
370 Tells C<$self> that the next action is to be called on a jstree
371 instance. For example:
372
373   $js->jstree->rename_node('tb-' . $text_block->id, $text_block->title);
374
375 =back
376
377 =head1 FUNCTIONS EVALUATED ON THE CLIENT SIDE
378
379 =head2 GENERIC FUNCTION
380
381 All of the following functions can be invoked in two ways: either by
382 calling the function name directly on C<$self> or by calling
383 L</action> with the function name as the first parameter. Therefore
384 the following two calls are identical:
385
386   $js->insertAfter($html, '#some-id');
387   $js->action('insertAfter', $html, '#some-id');
388
389 The second form, calling L</action>, is more to type but can be useful
390 in situations in which you have to call one of two functions depending
391 on context. For example, when you want to insert new code in a
392 list. If the list is empty you might have to use C<appendTo>, if it
393 isn't you might have to use C<insertAfter>. Example:
394
395   my $html = $self->render(...);
396   $js->action($list_is_empty ? 'appendTo' : 'insertAfter', $html, '#text-block-' . ($list_is_empty ? 'list' : $self->text_block->id));
397
398 Instead of:
399
400   my $html = $self->render(...);
401   if ($list_is_empty) {
402     $js->appendTo($html, '#text-block-list');
403   } else {
404     $js->insertAfter($html, '#text-block-' . $self->text_block->id);
405   }
406
407 The first variation is obviously better suited for chaining.
408
409 =over 4
410
411 =item C<action $method, @args>
412
413 Call the function with the name C<$method> on C<$self> with arguments
414 C<@args>. Returns the return value of the actual function
415 called. Useful for chaining (see above).
416
417 =item C<action_if $condition, $method, @args>
418
419 Call the function with the name C<$method> on C<$self> with arguments
420 C<@args> if C<$condition> is trueish. Does nothing otherwise.
421
422 Returns the return value of the actual function called if
423 C<$condition> is trueish and C<$self> otherwise. Useful for chaining
424 (see above).
425
426 This function is equivalent to the following:
427
428   if ($condition) {
429     $obj->$method(@args);
430   }
431
432 But it is easier to integrate into a method call chain, e.g.:
433
434   $js->html('#content', $html)
435      ->action_if($item->is_flagged, 'toggleClass', '#marker', 'flagged')
436      ->render($self);
437
438 =back
439
440 =head2 ADDITIONAL FUNCTIONS
441
442 =over 4
443
444 =item C<flash $type, $message>
445
446 Display a C<$message> in the flash of type C<$type>. Multiple calls of
447 C<flash> on the same C<$self> will be merged by type.
448
449 On the client side the flashes of all types will be cleared after each
450 successful ClientJS call that did not end with C<$js-E<gt>error(...)>.
451
452 =item C<error $message>
453
454 Causes L<to_json> (and therefore L<render>) to output a JSON object
455 that only contains an C<error> field set to this C<$message>. The
456 client will then show the message in the 'error' flash.
457
458 The messages of multiple calls of C<error> on the same C<$self> will
459 be merged.
460
461 =item C<redirect_to $url>
462
463 Redirects the browser window to the new URL by setting the JavaScript
464 property C<window.location.href>. Note that
465 L<SL::Controller::Base/redirect_to> is AJAX aware and uses this
466 function if the current request is an AJAX request as determined by
467 L<SL::Request/is_ajax>.
468
469 =back
470
471 =head2 KIVITENDO FUNCTIONS
472
473 The following functions from the C<kivi> namespace are supported:
474
475 =over 4
476
477 =item Displaying stuff
478
479 C<flash> (don't call directly, use L</flash> instead)
480
481 =item Running functions
482
483 C<run>, C<run_once_for>
484
485 =item Widgets
486
487 C<reinit_widgets>
488
489 =back
490
491 =head2 JQUERY FUNCTIONS
492
493 The following jQuery functions are supported:
494
495 =over 4
496
497 =item Basic effects
498
499 C<hide>, C<show>, C<toggle>
500
501 =item DOM insertion, around
502
503 C<unwrap>, C<wrap>, C<wrapAll>, C<wrapInner>
504
505 =item DOM insertion, inside
506
507 C<append>, C<appendTo>, C<html>, C<prepend>, C<prependTo>, C<text>
508
509 =item DOM insertion, outside
510
511 C<after>, C<before>, C<insertAfter>, C<insertBefore>
512
513 =item DOM removal
514
515 C<empty>, C<remove>
516
517 =item DOM replacement
518
519 C<replaceAll>, C<replaceWith>
520
521 =item General attributes
522
523 C<attr>, C<prop>, C<removeAttr>, C<removeProp>, C<val>
524
525 =item Class attributes
526
527 C<addClass>, C<removeClass>, C<toggleClass>
528
529 =item Data storage
530
531 C<data>, C<removeData>
532
533 =item Form Events
534
535 C<focus>
536
537 =item Generic Event Handlers
538
539 C<on>, C<off>, C<one>
540
541 These attach/detach event listeners to specific selectors. The first
542 argument is the selector, the second the name of the events and the
543 third argument is the name of the handler function. That function must
544 already exist when the handler is added.
545
546 =back
547
548 =head2 JQUERY POPUP DIALOG PLUGIN
549
550 Supported functions of the C<popup dialog> plugin to jQuery. They are
551 invoked by first calling C<dialog> in the ClientJS instance and then
552 the function itself:
553
554   $js->dialog->close(...);
555
556 =over 4
557
558 =item Closing and removing the popup
559
560 C<close>
561
562 =back
563
564 =head2 AJAXFORM JQUERY PLUGIN
565
566 The following functions of the C<ajaxForm> plugin to jQuery are
567 supported:
568
569 =over 4
570
571 =item All functions by the generic accessor function:
572
573 C<ajaxForm>
574
575 =back
576
577 =head2 JSTREE JQUERY PLUGIN
578
579 Supported functions of the C<jstree> plugin to jQuery. They are
580 invoked by first calling C<jstree> in the ClientJS instance and then
581 the function itself:
582
583   $js->jstree->open_node(...);
584
585 =over 4
586
587 =item Operations on the whole tree
588
589 C<lock>, C<unlock>
590
591 =item Opening and closing nodes
592
593 C<open_node>, C<close_node>, C<toggle_node>, C<open_all>,
594 C<close_all>, C<save_opened>, C<reopen>
595
596 =item Modifying nodes
597
598 C<rename_node>, C<delete_node>, C<move_node>
599
600 =item Selecting nodes (from the 'ui' jstree plugin)
601
602 C<select_node>, C<deselect_node>, C<deselect_all>
603
604 =back
605
606 =head1 ADDING SUPPORT FOR ADDITIONAL FUNCTIONS
607
608 In order not having to maintain two files (this one and
609 C<js/client_js.js>) there's a script that can parse this file's
610 C<%supported_methods> definition and generate the file
611 C<js/client_js.js> accordingly. The steps are:
612
613 =over 2
614
615 =item 1. Add lines in this file to the C<%supported_methods> hash. The
616 key is the function name and the value is the number of expected
617 parameters. The value can be negative to indicate that the function
618 takes at least the absolute of this value as parameters and optionally
619 more. In such a case the C<E<lt>ARGSE<gt>> format expands to an actual
620 array (and the individual elements if the value is positive>.
621
622 =item 2. Run C<scripts/generate_client_js_actions.pl>. It will
623 generate C<js/client_js.js> automatically.
624
625 =item 3. Reload the files in your browser (cleaning its cache can also
626 help).
627
628 =back
629
630 The template file used for generated C<js/client_js.js> is
631 C<scripts/generate_client_js_actions.tpl>.
632
633 =head1 BUGS
634
635 Nothing here yet.
636
637 =head1 AUTHOR
638
639 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
640
641 =cut