Formatfixes in Dokumentation

[mfinanz.git] / SL / Controller / Base.pm

diff --git a/SL/Controller/Base.pm b/SL/Controller/Base.pm
index 102631c8a5f9f7533a9ced842e3978c2083b9594..39bc692e7410a5382eeae8f43cab5b3e22fd94e3 100644 (file)
--- a/SL/Controller/Base.pm
+++ b/SL/Controller/Base.pm
@@ -1,21 +1,16 @@
 package SL::Controller::Base;
 
 package SL::Controller::Base;
 

+use strict;
+

 use parent qw(Rose::Object);
 
 use parent qw(Rose::Object);
 

+use Carp;

 use List::Util qw(first);
 
 #
 # public/helper functions
 #
 
 use List::Util qw(first);
 
 #
 # public/helper functions
 #
 

-sub parse_html_template {
-  my $self   = shift;
-  my $name   = shift;
-  my $locals = shift || {};
-
-  return $::form->parse_html_template($name, { %{ $locals }, SELF => $self });
-}
-

 sub url_for {
   my $self = shift;
 
 sub url_for {
   my $self = shift;
 


@@ -38,14 +33,92 @@ sub redirect_to {
 }
 
 sub render {
 }
 
 sub render {

-  my ($self, $template, %params) = @_;
+  my $self               = shift;
+  my $template           = shift;
+  my ($options, %locals) = (@_ && ref($_[0])) ? @_ : ({ }, @_);

 
 

-  if ($params{title}) {
-    $::form->{title} = delete $params{title};
+  my $source;
+  if ($options->{inline}) {
+    $source = \$template;
+
+  } else {
+    $source = "templates/webpages/${template}.html";
+    croak "Template file ${source} not found" unless -f $source;
+  }
+
+  if (!$options->{partial} && !$options->{inline}) {
+    $::form->{title} = $locals{title} if $locals{title};

     $::form->header;
   }
 
     $::form->header;
   }
 

-  print $self->parse_html_template($template, $params{locals});
+  my %params = ( %locals,
+                 AUTH     => $::auth,
+                 FORM     => $::form,
+                 LOCALE   => $::locale,
+                 LXCONFIG => { dbcharset              => $::dbcharset,
+                               webdav                 => $::webdav,
+                               lizenzen               => $::lizenzen,
+                               latex_templates        => $::latex,
+                               opendocument_templates => $::opendocument_templates,
+                               vertreter              => $::vertreter,
+                               show_best_before       => $::show_best_before,
+                             },
+                 LXDEBUG  => $::lxdebug,
+                 MYCONFIG => \%::myconfig,
+                 SELF     => $self,
+               );
+
+  my $output;
+  my $parser = $self->_template_obj;
+  $parser->process($source, \%params, \$output) || croak $parser->error;
+
+  print $output unless $options->{inline};
+
+  return $output;
+}
+
+#
+# Before/after run hooks
+#
+
+sub run_before {
+  _add_hook('before', @_);
+}
+
+sub run_after {
+  _add_hook('after', @_);
+}
+
+my %hooks;
+
+sub _add_hook {
+  my ($when, $class, $sub, %params) = @_;
+
+  foreach my $key (qw(only except)) {
+    $params{$key} = { map { ( $_ => 1 ) } @{ $params{$key} } } if $params{$key};
+  }
+
+  my $idx = "${when}/${class}";
+  $hooks{$idx} ||= [ ];
+  push @{ $hooks{$idx} }, { %params, code => $sub };
+}
+
+sub _run_hooks {
+  my ($self, $when, $action) = @_;
+
+  my $idx = "${when}/" . ref($self);
+
+  foreach my $hook (@{ $hooks{$idx} || [] }) {
+    next if ($hook->{only  } && !$hook->{only  }->{$action})
+         || ($hook->{except} &&  $hook->{except}->{$action});
+
+    if (ref($hook->{code}) eq 'CODE') {
+      $hook->{code}->($self);
+    } else {
+      my $sub = $hook->{code};
+      $self->$sub;
+    }
+  }

 }
 
 #
 }
 
 #


@@ -54,12 +127,16 @@ sub render {
 
 sub _run_action {
   my $self   = shift;
 
 sub _run_action {
   my $self   = shift;

-  my $action = "action_" . shift;
+  my $action = shift;
+  my $sub    = "action_${action}";
+
+  return $self->_dispatch(@_) if $action eq 'dispatch';

 
 

-  return $self->_dispatch(@_) if $action eq 'action_dispatch';
+  $::form->error("Invalid action '${action}' for controller " . ref($self)) if !$self->can($sub);

 
 

-  $::form->error("Invalid action ${action} for controller " . ref($self)) if !$self->can($action);
-  $self->$action(@_);
+  $self->_run_hooks('before', $action);
+  $self->$sub(@_);
+  $self->_run_hooks('after', $action);

 }
 
 sub _controller_name {
 }
 
 sub _controller_name {


@@ -69,10 +146,31 @@ sub _controller_name {
 sub _dispatch {
   my $self    = shift;
 
 sub _dispatch {
   my $self    = shift;
 

-  my @actions = grep { m/^action_/ } keys %{ ref($self) . "::" };
-  my $action  = first { $::form->{$_} } @actions;
+  no strict 'refs';
+  my @actions = map { s/^action_//; $_ } grep { m/^action_/ } keys %{ ref($self) . "::" };
+  my $action  = first { $::form->{"action_${_}"} } @actions;
+  my $sub     = "action_${action}";
+
+  $self->_run_hooks('before', $action);
+  $self->$sub(@_);
+  $self->_run_hooks('after', $action);
+}

 
 

-  $self->$action(@_);
+sub _template_obj {
+  my ($self) = @_;
+
+  $self->{__basepriv_template_obj} ||=
+    Template->new({ INTERPOLATE  => 0,
+                    EVAL_PERL    => 0,
+                    ABSOLUTE     => 1,
+                    CACHE_SIZE   => 0,
+                    PLUGIN_BASE  => 'SL::Template::Plugin',
+                    INCLUDE_PATH => '.:templates/webpages',
+                    COMPILE_EXT  => '.tcc',
+                    COMPILE_DIR  => $::userspath . '/templates-cache',
+                  }) || croak;
+
+  return $self->{__basepriv_template_obj};

 }
 
 1;
 }
 
 1;


@@ -154,6 +252,24 @@ Usage from a template usually looks like this:
 
 The dispatching is handled by the function L</_dispatch>.
 
 
 The dispatching is handled by the function L</_dispatch>.
 

+=head2 HOOKS
+
+Hooks are functions that are called before or after the controller's
+action is called. The controller package defines the hooks, and those
+hooks themselves are run as instance methods.
+
+Hooks are run in the order they're added.
+
+The return value of the hooks is discarded.
+
+Hooks can be defined to run for all actions, for only specific actions
+or for all actions except a list of actions. Each entry is the action
+name, not the sub's name. Therefore in order to run a hook before one
+of the subs C<action_edit> or C<action_save> is called the following
+code can be used:
+
+  __PACKAGE__->run_before('things_to_do_before_edit_and_save', only => [ 'edit', 'save' ]);
+

 =head1 FUNCTIONS
 
 =head2 PUBLIC HELPER FUNCTIONS
 =head1 FUNCTIONS
 
 =head2 PUBLIC HELPER FUNCTIONS


@@ -162,20 +278,61 @@ These functions are supposed to be called by sub-classed controllers.
 
 =over 4
 
 
 =over 4
 

-=item C<parse_html_template $file_name, $local_variables>
+=item C<render $template, [ $options, ] %locals>
+
+Renders the template C<$template>. Provides other variables than
+C<Form::parse_html_template> does.
+
+C<$options>, if present, must be a hash reference. All remaining
+parameters are slurped into C<%locals>.
+
+What is rendered and how C<$template> is interpreted is determined by
+C<< $options->{inline} >> and C<< $options->{partial} >>.

 
 

-Outputs an HTML template. It is a thin wrapper around
-C<Form::parse_html_template> which also adds the current object as the
-template variable C<SELF>.
+If C<< $options->{inline} >> is trueish then C<$template> is a string
+containing the template code to interprete. Additionally the output
+will not be sent to the browser. Instead it is only returned to the
+caller.

 
 

-=item C<render $template, %params>
+If C<< $options->{inline} >> is falsish then C<$template> is
+interpreted as the name of a template file. It is prefixed with
+"templates/webpages/" and postfixed with ".html". An exception will be
+thrown if that file does not exist.
+
+If C<< $options->{partial} >> or C<< $options->{inline} >> is trueish
+then C<< $::form->header >> will not be called. Otherwise
+C<< $::form->{header} >> will be set to C<$locals{header}> (only if
+$locals{header} is trueish) and C<< $::form->header >> will be called
+before the template itself is processed.
+
+The template itself has access to the following variables:
+
+=over 2

 
 

-Renders the template C<$template> by calling
-L</parse_html_template>. C<$params{locals}> will be used as the second
-parameter to L</parse_html_template>.
+=item * C<AUTH> -- C<$::auth>

 
 

-If C<$params{title}> is trueish then the function also sets
-C<< $::form->{header} >> to that value and calls C<< $::form->header >>.
+=item * C<FORM> -- C<$::form>
+
+=item * C<LOCALE> -- C<$::locale>
+
+=item * C<LXCONFIG> -- all parameters from C<config/lx-erp.conf> with
+the same name they appear in the file (e.g. C<dbcharset>, C<webdav>
+etc)
+
+=item * C<LXDEBUG> -- C<$::lxdebug>
+
+=item * C<MYCONFIG> -- C<%::myconfig>
+
+=item * C<SELF> -- the controller instance
+
+=item * All items from C<%locals>
+
+=back
+
+Unless C<< $options->{inline} >> is trueish the function will send the
+output to the browser.
+
+The function will always return the output.

 
 =item C<url_for $url>
 
 
 =item C<url_for $url>
 


@@ -204,12 +361,45 @@ Usage from a template might look like this:
 
   <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
 
 
   <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
 

-=item redirect_to %url_params
+=item C<redirect_to %url_params>

 
 Redirects the browser to a new URL by outputting a HTTP redirect
 header. The URL is generated by calling L</url_for> with
 C<%url_params>.
 
 
 Redirects the browser to a new URL by outputting a HTTP redirect
 header. The URL is generated by calling L</url_for> with
 C<%url_params>.
 

+=item C<run_before $sub, %params>
+
+=item C<run_after $sub, %params>
+
+Adds a hook to run before or after certain actions are run for the
+current package. The code to run is C<$sub> which is either the name
+of an instance method or a code reference. If it's the latter then the
+first parameter will be C<$self>.
+
+C<%params> can contain two possible values that restrict the code to
+be run only for certain actions:
+
+=over 2
+
+=item C<< only => \@list >>
+
+Only run the code for actions given in C<@list>. The entries are the
+action names, not the names of the sub (so it's C<list> instead of
+C<action_list>).
+
+=item C<< except => \@list >>
+
+Run the code for all actions but for those given in C<@list>. The
+entries are the action names, not the names of the sub (so it's
+C<list> instead of C<action_list>).
+
+=back
+
+If neither restriction is used then the code will be run for any
+action.
+
+The hook's return values are discarded.
+

 =back
 
 =head2 PRIVATE FUNCTIONS
 =back
 
 =head2 PRIVATE FUNCTIONS