package SL::Controller::Base;
+use strict;
+
use parent qw(Rose::Object);
+use Carp;
+use IO::File;
use List::Util qw(first);
+use SL::Request qw(flatten);
+use SL::MoreCommon qw(uri_encode);
+
+use Rose::Object::MakeMethods::Generic
+(
+ scalar => [ qw(action_name) ],
+);
#
# 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;
return $_[0] if (scalar(@_) == 1) && !ref($_[0]);
my %params = ref($_[0]) eq 'HASH' ? %{ $_[0] } : @_;
- my $controller = delete($params{controller}) || $self->_controller_name;
- my $action = delete($params{action}) || 'dispatch';
- $params{action} = "${controller}/${action}";
- my $query = join('&', map { $::form->escape($_) . '=' . $::form->escape($params{$_}) } keys %params);
+ my $controller = delete($params{controller}) || $self->controller_name;
+ my $action = $params{action} || 'dispatch';
+
+ my $script;
+ if ($controller =~ m/\.pl$/) {
+ # Old-style controller
+ $script = $controller;
+ } else {
+ $params{action} = "${controller}/${action}";
+ $script = "controller.pl";
+ }
+
+ my $query = join '&', map { uri_encode($_->[0]) . '=' . uri_encode($_->[1]) } @{ flatten(\%params) };
- return "controller.pl?${query}";
+ return "${script}?${query}";
}
sub redirect_to {
my $self = shift;
my $url = $self->url_for(@_);
- print $::cgi->redirect($url);
+ if ($self->delay_flash_on_redirect) {
+ require SL::Helper::Flash;
+ SL::Helper::Flash::delay_flash();
+ }
+
+ print $::request->{cgi}->redirect($url);
}
sub render {
- my $self = shift;
+ my $self = shift;
+ my $template = shift;
+ my ($options, %locals) = (@_ && ref($_[0])) ? @_ : ({ }, @_);
+
+ $options->{type} = lc($options->{type} || 'html');
+ $options->{no_layout} = 1 if $options->{type} eq 'js';
+
+ my $source;
+ if ($options->{inline}) {
+ $source = \$template;
+
+ } elsif($options->{raw}) {
+ $source = $template;
+
+ } else {
+ $source = "templates/webpages/${template}." . $options->{type};
+ croak "Template file ${source} not found" unless -f $source;
+ }
+
+ if (!$options->{partial} && !$options->{inline} && !$::form->{header}) {
+ if ($options->{no_layout}) {
+ $::form->{header} = 1;
+ my $content_type = $options->{type} eq 'js' ? 'text/javascript' : 'text/html';
+
+ print $::form->create_http_response(content_type => $content_type,
+ charset => $::lx_office_conf{system}->{dbcharset} || Common::DEFAULT_CHARSET());
+
+ } else {
+ $::form->{title} = $locals{title} if $locals{title};
+ $::form->header(no_menu => $options->{no_menu});
+ }
+ }
+
+ my %params = ( %locals,
+ AUTH => $::auth,
+ FLASH => $::form->{FLASH},
+ FORM => $::form,
+ INSTANCE_CONF => $::instance_conf,
+ LOCALE => $::locale,
+ LXCONFIG => \%::lx_office_conf,
+ LXDEBUG => $::lxdebug,
+ MYCONFIG => \%::myconfig,
+ SELF => $self,
+ );
+
+ my $output;
+ if (!$options->{raw}) {
+ my $parser = $self->_template_obj;
+ $parser->process($source, \%params, \$output) || croak $parser->error;
+ } else {
+ $output = $$source;
+ }
+
+ print $output unless $options->{inline} || $options->{no_output};
+
+ return $output;
+}
+
+sub send_file {
+ my ($self, $file_name, %params) = @_;
+
+ my $file = IO::File->new($file_name, 'r') || croak("Cannot open file '${file_name}'");
+ my $content_type = $params{type} || 'application/octet_stream';
+ my $attachment_name = $params{name} || $file_name;
+ $attachment_name =~ s:.*//::g;
+
+ print $::form->create_http_response(content_type => $content_type,
+ content_disposition => 'attachment; filename="' . $attachment_name . '"',
+ content_length => -s $file);
+
+ $::locale->with_raw_io(\*STDOUT, sub { print while <$file> });
+ $file->close;
+}
+
+sub controller_name {
+ my $class = ref($_[0]) || $_[0];
+ $class =~ s/^SL::Controller:://;
+ return $class;
+}
- my $template;
- $template = shift if scalar(@_) % 2;
- my %params = @_;
+#
+# 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) = @_;
- if ($params{title}) {
- $::form->{title} = delete $params{title};
- $::form->header;
+ foreach my $key (qw(only except)) {
+ $params{$key} = { map { ( $_ => 1 ) } @{ $params{$key} } } if $params{$key};
}
- print $self->parse_html_template($template, $params{locals});
+ 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, $action);
+ } else {
+ my $sub = $hook->{code};
+ $self->$sub($action);
+ }
+ }
+}
+
+#
+# behaviour. override these
+#
+
+sub delay_flash_on_redirect {
+ 0;
+}
+
+sub get_auth_level {
+ # Ignore the 'action' parameter.
+ return 'user';
+}
+
+sub keep_auth_vars_in_form {
+ return 0;
}
#
sub _run_action {
my $self = shift;
- my $action = "action_" . shift;
+ my $action = shift;
+ my $sub = "action_${action}";
- return $self->_dispatch(@_) if $action eq 'action_dispatch';
+ return $self->_dispatch(@_) if $action eq 'dispatch';
- $::form->error("Invalid action ${action} for controller " . ref($self)) if !$self->can($action);
- $self->$action(@_);
-}
+ $::form->error("Invalid action '${action}' for controller " . ref($self)) if !$self->can($sub);
-sub _controller_name {
- return (split(/::/, ref($_[0])))[-1];
+ $self->action_name($action);
+ $self->_run_hooks('before', $action);
+ $self->$sub(@_);
+ $self->_run_hooks('after', $action);
}
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}";
+
+ if ($self->can($sub)) {
+ $self->action_name($action);
+ $self->_run_hooks('before', $action);
+ $self->$sub(@_);
+ $self->_run_hooks('after', $action);
+ } else {
+ $::form->error($::locale->text('Oops. No valid action found to dispatch. Please report this case to the kivitendo team.'));
+ }
+}
- $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 => $::lx_office_conf{paths}->{userspath} . '/templates-cache',
+ ERROR => 'templates/webpages/generic/exception.html',
+ }) || croak;
+
+ return $self->{__basepriv_template_obj};
}
1;
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 hooks receive a single parameter: the name of the action that is
+about to be called (for C<before> hooks) / was called (for C<after>
+hooks).
+
+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
=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
+the options I<type>, I<inline>, I<partial> and I<no_layout>.
+
+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.
+
+If C<< $options->{raw} >> is trueish, the function will treat the input as
+already parsed, and will not filter the input through Template. Unlike
+C<inline>, the input is taked as a reference.
+
+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 a file extension based on
+C<< $options->{type} >>. C<< $options->{type} >> can be either C<html>
+or C<js> and defaults to C<html>. An exception will be thrown if that
+file does not exist.
+
+If C<< $options->{partial} >> or C<< $options->{inline} >> is trueish
+then neither the HTTP response header nor the standard HTML header is
+generated.
+
+Otherwise at least the HTTP response header will be generated based on
+the template type (C<< $options->{type} >>).
+
+If the template type is C<html> then the standard HTML header will be
+output via C<< $::form->header >> with C<< $::form->{title} >> set to
+C<$locals{title}> (the latter only if C<$locals{title}> is
+trueish). Setting C<< $options->{no_layout} >> to trueish will prevent
+this.
+
+The template itself has access to the following variables:
+
+=over 2
+
+=item * C<AUTH> -- C<$::auth>
+
+=item * C<FORM> -- C<$::form>
+
+=item * C<LOCALE> -- C<$::locale>
-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>.
+=item * C<LXCONFIG> -- all parameters from C<config/kivitendo.conf>
+with the same name they appear in the file (first level is the
+section, second the actual variable, e.g. C<system.dbcharset>,
+C<features.webdav> etc)
-=item C<render $template, %params>
+=item * C<LXDEBUG> -- C<$::lxdebug>
-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<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.
+
+Example: Render a HTML template with a certain title and a few locals
+
+ $self->render('todo/list',
+ title => 'List TODO items',
+ TODO_ITEMS => SL::DB::Manager::Todo->get_all_sorted);
+
+Example: Render a string and return its content for further processing
+by the calling function. No header is generated due to C<inline>.
+
+ my $content = $self->render('[% USE JavaScript %][% JavaScript.replace_with("#someid", "js/something") %]',
+ { type => 'js', inline => 1 });
+
+Example: Render a JavaScript template and send it to the
+browser. Typical use for actions called via AJAX:
+
+ $self->render('todo/single_item', { type => 'js' },
+ item => $employee->most_important_todo_item);
+
+=item C<send_file $file_name, [%params]>
+
+Sends the file C<$file_name> to the browser including appropriate HTTP
+headers for a download. C<%params> can include the following:
+
+=over 2
-If C<$params{title}> is trueish then the function also sets
-C<< $::form->{header} >> to that value and calls C<< $::form->header >>.
+=item * C<type> -- the file's content type; defaults to
+'application/octet_stream'
+
+=item * C<name> -- the name presented to the browser; defaults to
+C<$file_name>
+
+=back
=item C<url_for $url>
The controller to call is given by C<$params{controller}>. It defaults
to the current controller as returned by
-L</_controller_name>.
+L</controller_name>.
The action to call is given by C<$params{action}>. It defaults to
C<dispatch>.
<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>.
+=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
-=head2 PRIVATE FUNCTIONS
+If neither restriction is used then the code will be run for any
+action.
-These functions are supposed to be used from this base class only.
+The hook's return values are discarded.
-=over 4
+=item C<delay_flash_on_redirect>
-=item C<_controller_name>
+May be overridden by a controller. If this method returns true, redirect_to
+will delay all flash messages for the current request. Defaults to false for
+compatibility reasons.
+
+=item C<get_auth_level $action>
+
+May be overridden by a controller. Determines what kind of
+authentication is required for a particular action. Must return either
+C<admin> (which means that authentication as an admin is required),
+C<user> (authentication as a normal user suffices) with a possible
+future value C<none> (which would require no authentication but is not
+yet implemented).
+
+=item C<keep_auth_vars_in_form>
+
+May be overridden by a controller. If falsish (the default) all form
+variables whose name starts with C<{AUTH}> are removed before the
+request is routed. Only controllers that handle login requests
+themselves should return trueish for this function.
+
+=item C<controller_name>
Returns the name of the curernt controller package without the
-C<SL::Controller::> prefix.
+C<SL::Controller::> prefix. This method can be called both as a class
+method and an instance method.
+
+=item C<action_name>
+
+Returns the name of the currently executing action. If the dispatcher
+mechanism was used then this is not C<dispatch> but the actual method
+name the dispatching resolved to.
+
+=back
+
+=head2 PRIVATE FUNCTIONS
+
+These functions are supposed to be used from this base class only.
+
+=over 4
=item C<_dispatch>