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