projekt kivitendo

package SL::ClientJS;

use strict;

use parent qw(Rose::Object);

use Carp;

use SL::JSON ();

use Rose::Object::MakeMethods::Generic

(

  'scalar --get_set_init' => [ qw(_actions) ],

);

my %supported_methods = (

  # Basic effects

  hide         => 1,

  show         => 1,

  toggle       => 1,

  # DOM insertion, around

  unwrap       => 1,

  wrap         => 2,

  wrapAll      => 2,

  wrapInner    => 2,

  # DOM insertion, inside

  append       => 2,

  appendTo     => 2,

  html         => 2,

  prepend      => 2,

  prependTo    => 2,

  text         => 2,

  # DOM insertion, outside

  after        => 2,

  before       => 2,

  insertAfter  => 2,

  insertBefore => 2,

  # DOM removal

  empty        => 1,

  remove       => 1,

  # DOM replacement

  replaceAll   => 2,

  replaceWith  => 2,

  # General attributes

  attr         => 3,

  prop         => 3,

  removeAttr   => 2,

  removeProp   => 2,

  val          => 2,

  # Data storage

  data         => 3,

  removeData   => 2,

);

sub AUTOLOAD {

  our $AUTOLOAD;

  my ($self, @args) = @_;

  my $method        =  $AUTOLOAD;

  $method           =~ s/.*:://;

  return if $method eq 'DESTROY';

  my $num_args =  $supported_methods{$method};

  $::lxdebug->message(0, "autoload method $method");

  croak "Unsupported jQuery action: $method"                                                    unless defined $num_args;

  croak "Parameter count mismatch for $method(actual: " . scalar(@args) . " wanted: $num_args)" if     scalar(@args) != $num_args;

  if ($num_args) {

    # Force flattening from SL::Presenter::EscapedText: "" . $...

    $args[0] =  "" . $args[0];

    $args[0] =~ s/^\s+//;

  }

  push @{ $self->_actions }, [ $method, @args ];

  return $self;

}

sub init__actions {

  return [];

}

sub to_json {

  my ($self) = @_;

  return SL::JSON::to_json({ eval_actions => $self->_actions });

}

sub to_array {

  my ($self) = @_;

  return $self->_actions;

}

1;

__END__

=pod

=encoding utf8

=head1 NAME

SL::ClientJS - Easy programmatic client-side JavaScript generation

with jQuery

=head1 SYNOPSIS

First some JavaScript code:

  // In the client generate an AJAX request whose 'success' handler

  // calls "eval_json_response(data)":

  var data = {

    action: "SomeController/the_action",

    id:     $('#some_input_field').val()

  };

  $.post("controller.pl", data, eval_json_response);

Now some Perl code:

  # In the controller itself. First, make sure that the "client_js.js"

  # is loaded. This must be done when the whole side is loaded, so

  # it's not in the action called by the AJAX request shown above.

  $::request->layout->use_javascript('client_js.js');

  # Now in that action called via AJAX:

  sub action_the_action {

    my ($self) = @_;

    # Create a new client-side JS object and do stuff with it!

    my $js = SL::ClientJS->new;

    # Show some element on the page:

    $js->show('#usually_hidden');

    # Set to hidden inputs. Yes, calls can be chained!

    $js->val('#hidden_id', $self->new_id)

       ->val('#other_type', 'Unicorn');

    # Replace some HTML code:

    my $html = $self->render('SomeController/the_action', { output => 0 });

    $js->html('#id_with_new_content', $html);

    # Finally render the JSON response:

    $self->render($js);

  }

=head1 OVERVIEW

This module enables the generation of jQuery-using JavaScript code on

the server side. That code is then evaluated in a safe way on the

client side.

The workflow is usally that the client creates an AJAX request, the

server creates some actions and sends them back, and the client then

implements each of these actions.

There are three things that need to be done for this to work:

=over 2

=item 1. The "client_js.js" has to be loaded before the AJAX request is started.

=item 2. The client code needs to call C<eval_json_response()> with the result returned from the server.

=item 3. The server must use this module.

=back

The functions called on the client side are mostly jQuery

functions. Other functionality may be added later.

Note that L<SL::Controller/render> is aware of this module which saves

you some boilerplate. The following two calls are equivalent:

  $controller->render($client_js);

  $controller->render(\$client_js->to_json, { type => 'json' });

=head1 FUNCTIONS NOT PASSED TO THE CLIENT SIDE

=over 4

=item C<to_array>

Returns the actions gathered so far as an array reference. Each

element is an array reference containing at least two items: the

function's name and what it is called on. Additional array elements

are the function parameters.

=item C<to_json>

Returns the actions gathered so far as a JSON string ready to be sent

to the client.

=back

=head1 FUNCTIONS EVALUATED ON THE CLIENT SIDE

=head2 JQUERY FUNCTIONS

The following jQuery functions are supported:

=over 4

=item Basic effects

C<hide>, C<show>, C<toggle>

=item DOM insertion, around

C<unwrap>, C<wrap>, C<wrapAll>, C<wrapInner>

=item DOM insertion, inside

C<append>, C<appendTo>, C<html>, C<prepend>, C<prependTo>, C<text>

=item DOM insertion, outside

C<after>, C<before>, C<insertAfter>, C<insertBefore>

=item DOM removal

C<empty>, C<remove>

=item DOM replacement

C<replaceAll>, C<replaceWith>

=item General attributes

C<attr>, C<prop>, C<removeAttr>, C<removeProp>, C<val>

=item Data storage

C<data>, C<removeData>

=back

=head1 ADDING SUPPORT FOR ADDITIONAL FUNCTIONS

In order not having to maintain two files (this one and

C<js/client_js.js>) there's a script that can parse this file's

C<%supported_methods> definition and convert it into the appropriate

code ready for manual insertion into C<js/client_js.js>. The steps

are:

=over 2

=item 1. Add lines in this file to the C<%supported_methods> hash. The

key is the function name and the value is the number of expected

parameters.

=item 2. Run C<scripts/generate_client_js_actions.pl>

=item 3. Edit C<js/client_js.js> and replace the type casing code with

the output generated in step 2.

=back

=head1 BUGS

Nothing here yet.

=head1 AUTHOR

Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>

=cut

  # Special handling/shortcut for an instance of SL::ClientJS:

  return $self->render(\$template->to_json, { type => 'json' }) if ref($template) eq 'SL::ClientJS';

// NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE NOTE:

// Generate the dispatching lines in this script by running

// "scripts/generate_client_js_actions.pl". See the documentation for

// SL/ClientJS.pm for instructions.

function eval_json_result(data) {

  if (!data)

    return;

  if ((data.js || '') != '')

    eval(data.js);

  if (data.eval_actions)

    $(data.eval_actions).each(function(idx, action) {

      // console.log("ACTION " + action[0] + " ON " + action[1]);

      // Basic effects

           if (action[0] == 'hide')         $(action[1]).hide();

      else if (action[0] == 'show')         $(action[1]).show();

      else if (action[0] == 'toggle')       $(action[1]).toggle();

      // DOM insertion, around

      else if (action[0] == 'unwrap')       $(action[1]).unwrap();

      else if (action[0] == 'wrap')         $(action[1]).wrap(action[2]);

      else if (action[0] == 'wrapAll')      $(action[1]).wrapAll(action[2]);

      else if (action[0] == 'wrapInner')    $(action[1]).wrapInner(action[2]);

      // DOM insertion, inside

      else if (action[0] == 'append')       $(action[1]).append(action[2]);

      else if (action[0] == 'appendTo')     $(action[1]).appendTo(action[2]);

      else if (action[0] == 'html')         $(action[1]).html(action[2]);

      else if (action[0] == 'prepend')      $(action[1]).prepend(action[2]);

      else if (action[0] == 'prependTo')    $(action[1]).prependTo(action[2]);

      else if (action[0] == 'text')         $(action[1]).text(action[2]);

      // DOM insertion, outside

      else if (action[0] == 'after')        $(action[1]).after(action[2]);

      else if (action[0] == 'before')       $(action[1]).before(action[2]);

      else if (action[0] == 'insertAfter')  $(action[1]).insertAfter(action[2]);

      else if (action[0] == 'insertBefore') $(action[1]).insertBefore(action[2]);

      // DOM removal

      else if (action[0] == 'empty')        $(action[1]).empty();

      else if (action[0] == 'remove')       $(action[1]).remove();

      // DOM replacement

      else if (action[0] == 'replaceAll')   $(action[1]).replaceAll(action[2]);

      else if (action[0] == 'replaceWith')  $(action[1]).replaceWith(action[2]);

      // General attributes

      else if (action[0] == 'attr')         $(action[1]).attr(action[2], action[3]);

      else if (action[0] == 'prop')         $(action[1]).prop(action[2], action[3]);

      else if (action[0] == 'removeAttr')   $(action[1]).removeAttr(action[2]);

      else if (action[0] == 'removeProp')   $(action[1]).removeProp(action[2]);

      else if (action[0] == 'val')          $(action[1]).val(action[2]);

      // Data storage

      else if (action[0] == 'data')         $(action[1]).data(action[2], action[3]);

      else if (action[0] == 'removeData')   $(action[1]).removeData(action[2]);

      else                                  console.log("Unknown action: " + action[0]);

    });

  console.log("current_content_type " + $('#current_content_type').val() + ' ID ' + $('#current_content_id').val());

}

#!/usr/bin/perl

use strict;

use warnings;

use File::Slurp;

use List::Util qw(first max);

my $file_name = (first { -f } qw(SL/ClientJS.pm ../SL/ClientJS.pm)) || die "ClientJS.pm not found";

my @actions;

foreach (read_file($file_name)) {

  chomp;

  next unless (m/^my \%supported_methods/ .. m/^\);/);

  push @actions, [ 'action',  $1, $2 ] if m/^\s+([a-zA-Z]+)\s*=>\s*(\d+),$/;

  push @actions, [ 'comment', $1     ] if m/^\s+#\s+(.+)/;

}

my $longest   = max map { length($_->[1]) } grep { $_->[0] eq 'action' } @actions;

my $first     = 1;

my $output;

#      else if (action[0] == 'hide')        $(action[1]).hide();

foreach my $action (@actions) {

  if ($action->[0] eq 'comment') {

    print "\n" unless $first;

    print "      // ", $action->[1], "\n";

  } else {

    my $args = $action->[2] == 1 ? '' : join(', ', map { "action[$_]" } (2..$action->[2]));

    printf('      %s if (action[0] == \'%s\')%s $(action[1]).%s(%s);' . "\n",

           $first ? '    ' : 'else',

           $action->[1],

           ' ' x ($longest - length($action->[1])),

           $action->[1],

           $args);

    $first = 0;

  }

}

printf "\n      else\%sconsole.log('Unknown action: ' + action[0]);\n", ' ' x (4 + 2 + 6 + 3 + 4 + 2 + $longest + 1);