1 package SL::Controller::Base;
5 use parent qw(Rose::Object);
9 use List::Util qw(first);
10 use SL::Request qw(flatten);
11 use SL::MoreCommon qw(uri_encode);
14 use Rose::Object::MakeMethods::Generic
16 scalar => [ qw(action_name) ],
20 # public/helper functions
26 return $_[0] if (scalar(@_) == 1) && !ref($_[0]);
28 my %params = ref($_[0]) eq 'HASH' ? %{ $_[0] } : @_;
29 my $controller = delete($params{controller}) || $self->controller_name;
30 my $action = $params{action} || 'dispatch';
33 if ($controller =~ m/\.pl$/) {
34 # Old-style controller
35 $script = $controller;
37 $params{action} = "${controller}/${action}";
38 $script = "controller.pl";
41 my $query = join '&', map { uri_encode($_->[0]) . '=' . uri_encode($_->[1]) } @{ flatten(\%params) };
43 return "${script}?${query}";
48 my $url = $self->url_for(@_);
50 if ($self->delay_flash_on_redirect) {
51 require SL::Helper::Flash;
52 SL::Helper::Flash::delay_flash();
55 print $::request->{cgi}->redirect($url);
61 my ($options, %locals) = (@_ && ref($_[0])) ? @_ : ({ }, @_);
63 # Special handling/shortcut for an instance of SL::ClientJS:
64 return $self->render(\$template->to_json, { type => 'json' }) if ref($template) eq 'SL::ClientJS';
66 # Set defaults for all available options.
74 $options->{$_} //= $defaults{$_} for keys %defaults;
75 $options->{type} = lc $options->{type};
77 # Check supplied options for validity.
78 foreach (keys %{ $options }) {
79 croak "Unsupported option: $_" unless $defaults{$_};
82 # Only certain types are supported.
83 croak "Unsupported type: " . $options->{type} unless $options->{type} =~ m/^(?:html|js|json)$/;
85 # The "template" argument must be a string or a reference to one.
86 $template = ${ $template } if ((ref($template) || '') eq 'REF') && (ref(${ $template }) eq 'SL::Presenter::EscapedText');
87 croak "Unsupported 'template' reference type: " . ref($template) if ref($template) && (ref($template) !~ m/^(?:SCALAR|SL::Presenter::EscapedText)$/);
89 # If all output is turned off then don't output the header either.
90 if (!$options->{output}) {
91 $options->{header} = 0;
92 $options->{layout} = 0;
95 # Layout only makes sense if we're outputting HTML.
96 $options->{layout} = 0 if $options->{type} ne 'html';
99 if ($options->{header}) {
100 # Output the HTTP response and the layout in case of HTML output.
102 if ($options->{layout}) {
103 $::form->{title} = $locals{title} if $locals{title};
107 # No layout: just the standard HTTP response. Also notify
108 # $::form that the header has already been output so that
109 # $::form->header() won't output it again.
110 $::form->{header} = 1;
111 my $content_type = $options->{type} eq 'html' ? 'text/html'
112 : $options->{type} eq 'js' ? 'text/javascript'
113 : 'application/json';
115 print $::form->create_http_response(content_type => $content_type,
116 charset => $::lx_office_conf{system}->{dbcharset} || Common::DEFAULT_CHARSET());
120 # Let the presenter do the rest of the work.
121 my $output = $self->presenter->render(
123 { type => $options->{type}, process => $options->{process} },
128 # Print the output if wanted.
129 print $output if $options->{output};
135 my ($self, $file_name, %params) = @_;
137 my $file = IO::File->new($file_name, 'r') || croak("Cannot open file '${file_name}'");
138 my $content_type = $params{type} || 'application/octet_stream';
139 my $attachment_name = $params{name} || $file_name;
140 $attachment_name =~ s:.*//::g;
142 print $::form->create_http_response(content_type => $content_type,
143 content_disposition => 'attachment; filename="' . $attachment_name . '"',
144 content_length => -s $file);
146 $::locale->with_raw_io(\*STDOUT, sub { print while <$file> });
151 return SL::Presenter->get;
154 sub controller_name {
155 my $class = ref($_[0]) || $_[0];
156 $class =~ s/^SL::Controller:://;
161 # Before/after run hooks
165 _add_hook('before', @_);
169 _add_hook('after', @_);
175 my ($when, $class, $sub, %params) = @_;
177 foreach my $key (qw(only except)) {
178 $params{$key} = { map { ( $_ => 1 ) } @{ $params{$key} } } if $params{$key};
181 my $idx = "${when}/${class}";
182 $hooks{$idx} ||= [ ];
183 push @{ $hooks{$idx} }, { %params, code => $sub };
187 my ($self, $when, $action) = @_;
189 my $idx = "${when}/" . ref($self);
191 foreach my $hook (@{ $hooks{$idx} || [] }) {
192 next if ($hook->{only } && !$hook->{only }->{$action})
193 || ($hook->{except} && $hook->{except}->{$action});
195 if (ref($hook->{code}) eq 'CODE') {
196 $hook->{code}->($self, $action);
198 my $sub = $hook->{code};
199 $self->$sub($action);
205 # behaviour. override these
208 sub delay_flash_on_redirect {
213 # Ignore the 'action' parameter.
217 sub keep_auth_vars_in_form {
222 # private functions -- for use in Base only
228 my $sub = "action_${action}";
230 return $self->_dispatch(@_) if $action eq 'dispatch';
232 $::form->error("Invalid action '${action}' for controller " . ref($self)) if !$self->can($sub);
234 $self->action_name($action);
235 $self->_run_hooks('before', $action);
237 $self->_run_hooks('after', $action);
244 my @actions = map { s/^action_//; $_ } grep { m/^action_/ } keys %{ ref($self) . "::" };
245 my $action = first { $::form->{"action_${_}"} } @actions;
246 my $sub = "action_${action}";
248 if ($self->can($sub)) {
249 $self->action_name($action);
250 $self->_run_hooks('before', $action);
252 $self->_run_hooks('after', $action);
254 $::form->error($::locale->text('Oops. No valid action found to dispatch. Please report this case to the kivitendo team.'));
264 SL::Controller::Base - base class for all action controllers
270 This is a base class for all action controllers. Action controllers
271 provide subs that are callable by special URLs.
273 For each request made to the web server an instance of the controller
274 will be created. After the request has been served that instance will
275 handed over to garbage collection.
277 This base class is derived from L<Rose::Object>.
281 The URLs have the following properties:
287 The script part of the URL must be C<controller.pl>.
291 There must be a GET or POST parameter named C<action> containing the
292 name of the controller and the sub to call separated by C</>,
293 e.g. C<Message/list>.
297 The controller name is the package's name without the
298 C<SL::Controller::> prefix. At the moment only packages in the
299 C<SL::Controller> namespace are valid; sub-namespaces are not
300 allowed. The package name must start with an upper-case letter.
304 The sub part of the C<action> parameter is the name of the sub to
305 call. However, the sub's name is automatically prefixed with
306 C<action_>. Therefore for the example C<Message/list> the sub
307 C<SL::DB::Message::action_list> would be called. This in turn means
308 that subs whose name does not start with C<action_> cannot be invoked
309 directly via the URL.
313 =head2 INDIRECT DISPATCHING
315 In the case that there are several submit buttons on a page it is
316 often impractical to have a single C<action> parameter match up
317 properly. For such a case a special dispatcher method is available. In
318 that case the C<action> parameter of the URL must be
319 C<Controller/dispatch>.
321 The C<SL::Controller::Base::_dispatch> method will iterate over all
322 subs in the controller package whose names start with C<action_>. The
323 first one for which there's a GET or POST parameter with the same name
324 and that's trueish is called.
326 Usage from a template usually looks like this:
328 <form method="POST" action="controller.pl">
330 <input type="hidden" name="action" value="Message/dispatch">
331 <input type="submit" name="action_mark_as_read" value="Mark messages as read">
332 <input type="submit" name="action_delete" value="Delete messages">
335 The dispatching is handled by the function L</_dispatch>.
339 Hooks are functions that are called before or after the controller's
340 action is called. The controller package defines the hooks, and those
341 hooks themselves are run as instance methods.
343 Hooks are run in the order they're added.
345 The hooks receive a single parameter: the name of the action that is
346 about to be called (for C<before> hooks) / was called (for C<after>
349 The return value of the hooks is discarded.
351 Hooks can be defined to run for all actions, for only specific actions
352 or for all actions except a list of actions. Each entry is the action
353 name, not the sub's name. Therefore in order to run a hook before one
354 of the subs C<action_edit> or C<action_save> is called the following
357 __PACKAGE__->run_before('things_to_do_before_edit_and_save', only => [ 'edit', 'save' ]);
361 =head2 PUBLIC HELPER FUNCTIONS
363 These functions are supposed to be called by sub-classed controllers.
367 =item C<render $template, [ $options, ] %locals>
369 Renders the template C<$template>. Provides other variables than
370 C<Form::parse_html_template> does.
372 C<$options>, if present, must be a hash reference. All remaining
373 parameters are slurped into C<%locals>.
375 What is rendered and how C<$template> is interpreted is determined
376 both by C<$template>'s reference type and by the supplied options. The
377 actual rendering is handled by L<SL::Presenter/render>.
379 If C<$template> is a normal scalar (not a reference) then it is meant
380 to be a template file name relative to the C<templates/webpages>
381 directory. The file name to use is determined by the C<type> option.
383 If C<$template> is a reference to a scalar then the referenced
384 scalar's content is used as the content to process. The C<type> option
385 is not considered in this case.
387 C<$template> can also be an instance of L<SL::Presenter::EscapedText>
388 or a reference to such an instance. Both of these cases are handled
389 the same way as if C<$template> were a reference to a scalar: its
390 content is processed, and C<type> is not considered.
392 Other reference types, unknown options and unknown arguments to the
393 C<type> option cause the function to L<croak>.
395 The following options are available (defaults: C<type> = 'html',
396 C<process> = 1, C<output> = 1, C<header> = 1, C<layout> = 1):
402 The template type. Can be C<html> (the default), C<js> for JavaScript
403 or C<json> for JSON content. Affects the extension that's added to the
404 file name given with a non-reference C<$template> argument, the
405 content type HTTP header that is output and whether or not the layout
406 will be output as well (see description of C<layout> below).
410 If trueish (which is also the default) it causes the template/content
411 to be processed by the Template toolkit. Otherwise the
412 template/content is output as-is.
416 If trueish (the default) then the generated output will be sent to the
417 browser in addition to being returned. If falsish then the options
418 C<header> and C<layout> are set to 0 as well.
422 Determines whether or not to output the HTTP response
423 headers. Defaults to the same value that C<output> is set to. If set
424 to falsish then the layout is not output either.
428 Determines whether or not the basic HTML layout structure should be
429 output (HTML header, common JavaScript and stylesheet inclusions, menu
430 etc.). Defaults to 0 if C<type> is not C<html> and to the same value
431 C<header> is set to otherwise.
435 The template itself has access to several variables. These are listed
436 in the documentation to L<SL::Presenter/render>.
438 The function will always return the output.
440 Example: Render a HTML template with a certain title and a few locals
442 $self->render('todo/list',
443 title => 'List TODO items',
444 TODO_ITEMS => SL::DB::Manager::Todo->get_all_sorted);
446 Example: Render a string and return its content for further processing
447 by the calling function. No header is generated due to C<output>.
449 my $content = $self->render(\'[% USE JavaScript %][% JavaScript.replace_with("#someid", "js/something") %]',
452 Example: Render a JavaScript template
453 "templates/webpages/todo/single_item.js" and send it to the
454 browser. Typical use for actions called via AJAX:
456 $self->render('todo/single_item', { type => 'js' },
457 item => $employee->most_important_todo_item);
459 =item C<send_file $file_name, [%params]>
461 Sends the file C<$file_name> to the browser including appropriate HTTP
462 headers for a download. C<%params> can include the following:
466 =item * C<type> -- the file's content type; defaults to
467 'application/octet_stream'
469 =item * C<name> -- the name presented to the browser; defaults to
474 =item C<url_for $url>
476 =item C<url_for $params>
478 =item C<url_for %params>
480 Creates an URL for the given parameters suitable for calling an action
481 controller. If there's only one scalar parameter then it is returned
484 Otherwise the parameters are given either as a single hash ref
485 parameter or as a normal hash.
487 The controller to call is given by C<$params{controller}>. It defaults
488 to the current controller as returned by
491 The action to call is given by C<$params{action}>. It defaults to
494 All other key/value pairs in C<%params> are appended as GET parameters
497 Usage from a template might look like this:
499 <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
501 =item C<redirect_to %url_params>
503 Redirects the browser to a new URL by outputting a HTTP redirect
504 header. The URL is generated by calling L</url_for> with
507 =item C<run_before $sub, %params>
509 =item C<run_after $sub, %params>
511 Adds a hook to run before or after certain actions are run for the
512 current package. The code to run is C<$sub> which is either the name
513 of an instance method or a code reference. If it's the latter then the
514 first parameter will be C<$self>.
516 C<%params> can contain two possible values that restrict the code to
517 be run only for certain actions:
521 =item C<< only => \@list >>
523 Only run the code for actions given in C<@list>. The entries are the
524 action names, not the names of the sub (so it's C<list> instead of
527 =item C<< except => \@list >>
529 Run the code for all actions but for those given in C<@list>. The
530 entries are the action names, not the names of the sub (so it's
531 C<list> instead of C<action_list>).
535 If neither restriction is used then the code will be run for any
538 The hook's return values are discarded.
540 =item C<delay_flash_on_redirect>
542 May be overridden by a controller. If this method returns true, redirect_to
543 will delay all flash messages for the current request. Defaults to false for
544 compatibility reasons.
546 =item C<get_auth_level $action>
548 May be overridden by a controller. Determines what kind of
549 authentication is required for a particular action. Must return either
550 C<admin> (which means that authentication as an admin is required),
551 C<user> (authentication as a normal user suffices) with a possible
552 future value C<none> (which would require no authentication but is not
555 =item C<keep_auth_vars_in_form>
557 May be overridden by a controller. If falsish (the default) all form
558 variables whose name starts with C<{AUTH}> are removed before the
559 request is routed. Only controllers that handle login requests
560 themselves should return trueish for this function.
562 =item C<controller_name>
564 Returns the name of the curernt controller package without the
565 C<SL::Controller::> prefix. This method can be called both as a class
566 method and an instance method.
570 Returns the name of the currently executing action. If the dispatcher
571 mechanism was used then this is not C<dispatch> but the actual method
572 name the dispatching resolved to.
576 Returns the global presenter object by calling
577 L<SL::Presenter/get>.
581 =head2 PRIVATE FUNCTIONS
583 These functions are supposed to be used from this base class only.
589 Implements the method lookup for indirect dispatching mentioned in the
590 section L</INDIRECT DISPATCHING>.
592 =item C<_run_action $action>
594 Executes a sub based on the value of C<$action>. C<$action> is the sub
595 name part of the C<action> GET or POST parameter as described in
598 If C<$action> equals C<dispatch> then the sub L</_dispatch> in this
599 base class is called for L</INDIRECT DISPATCHING>. Otherwise
600 C<$action> is prefixed with C<action_>, and that sub is called on the
601 current controller instance.
607 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>