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