AttrDuration-Helfer

[mfinanz.git] / SL / ClientJS.pm

diff --git a/SL/ClientJS.pm b/SL/ClientJS.pm
index 47f8a225b814e00905d93d795e090bff3611ab06..51f663fa52c50b7db1941c0d94037c0cdbdcdff2 100644 (file)
--- a/SL/ClientJS.pm
+++ b/SL/ClientJS.pm
@@ -9,10 +9,15 @@ use SL::JSON ();
 
 use Rose::Object::MakeMethods::Generic
 (
 
 use Rose::Object::MakeMethods::Generic
 (

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

 );
 
 my %supported_methods = (
 );
 
 my %supported_methods = (

+  # ## Non-jQuery methods ##
+  flash        => 2,            # display_flash(<TARGET>, <ARGS>)
+
+  # ## jQuery basics ##
+

   # Basic effects
   hide         => 1,
   show         => 1,
   # Basic effects
   hide         => 1,
   show         => 1,


@@ -56,6 +61,35 @@ my %supported_methods = (
   # Data storage
   data         => 3,
   removeData   => 2,
   # Data storage
   data         => 3,
   removeData   => 2,

+
+  # Form Events
+  focus        => 1,
+
+  # ## jstree plugin ## pattern: $.jstree._reference($(<TARGET>)).<FUNCTION>(<ARGS>)
+
+  # Operations on the whole tree
+  'jstree:lock'          => 1,
+  'jstree:unlock'        => 1,
+
+  # Opening and closing nodes
+  'jstree:open_node'     => 2,
+  'jstree:open_all'      => 2,
+  'jstree:close_node'    => 2,
+  'jstree:close_all'     => 2,
+  'jstree:toggle_node'   => 2,
+  'jstree:save_opened'   => 1,
+  'jstree:reopen'        => 1,
+
+  # Modifying nodes
+  'jstree:create_node'   => 4,
+  'jstree:rename_node'   => 3,
+  'jstree:delete_node'   => 2,
+  'jstree:move_node'     => 5,
+
+  # Selecting nodes (from the 'ui' plugin to jstree)
+  'jstree:select_node'   => 2,  # $.jstree._reference($(<TARGET>)).<FUNCTION>(<ARGS>, true)
+  'jstree:deselect_node' => 2,
+  'jstree:deselect_all'  => 1,

 );
 
 sub AUTOLOAD {
 );
 
 sub AUTOLOAD {


@@ -66,9 +100,14 @@ sub AUTOLOAD {
   my $method        =  $AUTOLOAD;
   $method           =~ s/.*:://;
   return if $method eq 'DESTROY';
   my $method        =  $AUTOLOAD;
   $method           =~ s/.*:://;
   return if $method eq 'DESTROY';

+  return $self->action($method, @args);
+}
+
+sub action {
+  my ($self, $method, @args) = @_;

 
 

+  $method      =  (delete($self->{_prefix}) || '') . $method;

   my $num_args =  $supported_methods{$method};
   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;
 
   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;


@@ -88,8 +127,18 @@ sub init__actions {
   return [];
 }
 
   return [];
 }
 

+sub init__flash {
+  return {};
+}
+
+sub init__error {
+  return '';
+}
+

 sub to_json {
   my ($self) = @_;
 sub to_json {
   my ($self) = @_;

+
+  return SL::JSON::to_json({ error        => $self->_error   }) if $self->_error;

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


@@ -98,6 +147,40 @@ sub to_array {
   return $self->_actions;
 }
 
   return $self->_actions;
 }
 

+sub render {
+  my ($self, $controller) = @_;
+  return $controller->render(\$self->to_json, { type => 'json' });
+}
+
+sub jstree {
+  my ($self) = @_;
+  $self->{_prefix} = 'jstree:';
+  return $self;
+}
+
+sub flash {
+  my ($self, $type, @messages) = @_;
+
+  my $message = join ' ', grep { $_ } @messages;
+
+  if (!$self->_flash->{$type}) {
+    $self->_flash->{$type} = [ 'flash', $type, $message ];
+    push @{ $self->_actions }, $self->_flash->{$type};
+  } else {
+    $self->_flash->{$type}->[-1] .= ' ' . $message;
+  }
+
+  return $self;
+}
+
+sub error {
+  my ($self, @messages) = @_;
+
+  $self->_error(join ' ', grep { $_ } ($self->_error, @messages));
+
+  return $self;
+}
+

 1;
 __END__
 
 1;
 __END__
 


@@ -147,8 +230,17 @@ Now some Perl code:
     my $html = $self->render('SomeController/the_action', { output => 0 });
     $js->html('#id_with_new_content', $html);
 
     my $html = $self->render('SomeController/the_action', { output => 0 });
     $js->html('#id_with_new_content', $html);
 

+    # Operations on a jstree: rename a node and select it
+    my $text_block = SL::DB::RequirementSpecTextBlock->new(id => 4711)->load;
+    $js->jstree->rename_node('#tb-' . $text_block->id, $text_block->title)
+       ->jstree->select_node('#tb-' . $text_block->id);
+

     # Finally render the JSON response:
     $self->render($js);
     # Finally render the JSON response:
     $self->render($js);

+
+    # Rendering can also be chained, e.g.
+    $js->html('#selector', $html)
+       ->render($self);

   }
 
 =head1 OVERVIEW
   }
 
 =head1 OVERVIEW


@@ -198,10 +290,77 @@ are the function parameters.
 Returns the actions gathered so far as a JSON string ready to be sent
 to the client.
 
 Returns the actions gathered so far as a JSON string ready to be sent
 to the client.
 

+=item C<render $controller>
+
+Renders C<$self> via the controller. Useful for chaining. Equivalent
+to the following:
+
+  $controller->render(\$self->to_json, { type => 'json' });
+
+=item C<jstree>
+
+Tells C<$self> that the next action is to be called on a jstree
+instance. For example:
+
+  $js->jstree->rename_node('tb-' . $text_block->id, $text_block->title);
+

 =back
 
 =head1 FUNCTIONS EVALUATED ON THE CLIENT SIDE
 
 =back
 
 =head1 FUNCTIONS EVALUATED ON THE CLIENT SIDE
 

+=head2 GENERIC FUNCTION
+
+All of the following functions can be invoked in two ways: either by
+calling the function name directly on C<$self> or by calling
+L</action> with the function name as the first parameter. Therefore
+the following two calls are identical:
+
+  $js->insertAfter($html, '#some-id');
+  $js->action('insertAfter', $html, '#some-id');
+
+The second form, calling L</action>, is more to type but can be useful
+in situations in which you have to call one of two functions depending
+on context. For example, when you want to insert new code in a
+list. If the list is empty you might have to use C<appendTo>, if it
+isn't you might have to use C<insertAfter>. Example:
+
+  my $html = $self->render(...);
+  $js->action($list_is_empty ? 'appendTo' : 'insertAfter', $html, '#text-block-' . ($list_is_empty ? 'list' : $self->text_block->id));
+
+Instead of:
+
+  my $html = $self->render(...);
+  if ($list_is_empty) {
+    $js->appendTo($html, '#text-block-list');
+  } else {
+    $js->insertAfter($html, '#text-block-' . $self->text_block->id);
+  }
+
+The first variation is obviously better suited for chaining.
+
+Additional functions:
+
+=over 4
+
+=item C<flash $type, $message>
+
+Display a C<$message> in the flash of type C<$type>. Multiple calls of
+C<flash> on the same C<$self> will be merged by type.
+
+On the client side the flash of this type will be cleared before the
+message is shown.
+
+=item C<error $message>
+
+Causes L<to_json> (and therefore L<render>) to output a JSON object
+that only contains an C<error> field set to this C<$message>. The
+client will then show the message in the 'error' flash.
+
+The messages of multiple calls of C<error> on the same C<$self> will
+be merged.
+
+=back
+

 =head2 JQUERY FUNCTIONS
 
 The following jQuery functions are supported:
 =head2 JQUERY FUNCTIONS
 
 The following jQuery functions are supported:


@@ -240,15 +399,44 @@ C<attr>, C<prop>, C<removeAttr>, C<removeProp>, C<val>
 
 C<data>, C<removeData>
 
 
 C<data>, C<removeData>
 

+=item Form Events
+
+C<focus>
+
+=back
+
+=head2 JSTREE JQUERY PLUGIN
+
+The following functions of the C<jstree> plugin to jQuery are
+supported:
+
+=over 4
+
+=item Operations on the whole tree
+
+C<lock>, C<unlock>
+
+=item Opening and closing nodes
+
+C<open_node>, C<close_node>, C<toggle_node>, C<open_all>,
+C<close_all>, C<save_opened>, C<reopen>
+
+=item Modifying nodes
+
+C<rename_node>, C<delete_node>, C<move_node>
+
+=item Selecting nodes (from the 'ui' jstree plugin)
+
+C<select_node>, C<deselect_node>, C<deselect_all>
+

 =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
 =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:
+C<%supported_methods> definition and generate the file
+C<js/client_js.js> accordingly. The steps are:

 
 =over 2
 
 
 =over 2
 


@@ -256,13 +444,17 @@ are:
 key is the function name and the value is the number of expected
 parameters.
 
 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 2. Run C<scripts/generate_client_js_actions.pl>. It will
+generate C<js/client_js.js> automatically.

 
 

-=item 3. Edit C<js/client_js.js> and replace the type casing code with
-the output generated in step 2.
+=item 3. Reload the files in your browser (cleaning its cache can also
+help).

 
 =back
 
 
 =back
 

+The template file used for generated C<js/client_js.js> is
+C<scripts/generate_client_js_actions.tpl>.
+

 =head1 BUGS
 
 Nothing here yet.
 =head1 BUGS
 
 Nothing here yet.