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