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 # Set defaults for all available options.
71 $options->{$_} //= $defaults{$_} for keys %defaults;
72 $options->{type} = lc $options->{type};
74 # Check supplied options for validity.
75 foreach (keys %{ $options }) {
76 croak "Unsupported option: $_" unless $defaults{$_};
79 # Only certain types are supported.
80 croak "Unsupported type: " . $options->{type} unless $options->{type} =~ m/^(?:html|js|json)$/;
82 # The "template" argument must be a string or a reference to one.
83 $template = ${ $template } if ((ref($template) || '') eq 'REF') && (ref(${ $template }) eq 'SL::Presenter::EscapedText');
84 croak "Unsupported 'template' reference type: " . ref($template) if ref($template) && (ref($template) !~ m/^(?:SCALAR|SL::Presenter::EscapedText)$/);
86 # If all output is turned off then don't output the header either.
87 if (!$options->{output}) {
88 $options->{header} = 0;
89 $options->{layout} = 0;
92 # Layout only makes sense if we're outputting HTML.
93 $options->{layout} = 0 if $options->{type} ne 'html';
96 if ($options->{header}) {
97 # Output the HTTP response and the layout in case of HTML output.
99 if ($options->{layout}) {
100 $::form->{title} = $locals{title} if $locals{title};
104 # No layout: just the standard HTTP response. Also notify
105 # $::form that the header has already been output so that
106 # $::form->header() won't output it again.
107 $::form->{header} = 1;
108 my $content_type = $options->{type} eq 'html' ? 'text/html'
109 : $options->{type} eq 'js' ? 'text/javascript'
110 : 'application/json';
112 print $::form->create_http_response(content_type => $content_type,
113 charset => $::lx_office_conf{system}->{dbcharset} || Common::DEFAULT_CHARSET());
117 # Let the presenter do the rest of the work.
118 my $output = $self->presenter->render(
120 { type => $options->{type}, process => $options->{process} },
125 # Print the output if wanted.
126 print $output if $options->{output};
132 my ($self, $file_name, %params) = @_;
134 my $file = IO::File->new($file_name, 'r') || croak("Cannot open file '${file_name}'");
135 my $content_type = $params{type} || 'application/octet_stream';
136 my $attachment_name = $params{name} || $file_name;
137 $attachment_name =~ s:.*//::g;
139 print $::form->create_http_response(content_type => $content_type,
140 content_disposition => 'attachment; filename="' . $attachment_name . '"',
141 content_length => -s $file);
143 $::locale->with_raw_io(\*STDOUT, sub { print while <$file> });
148 return SL::Presenter->get;
151 sub controller_name {
152 my $class = ref($_[0]) || $_[0];
153 $class =~ s/^SL::Controller:://;
158 # Before/after run hooks
162 _add_hook('before', @_);
166 _add_hook('after', @_);
172 my ($when, $class, $sub, %params) = @_;
174 foreach my $key (qw(only except)) {
175 $params{$key} = { map { ( $_ => 1 ) } @{ $params{$key} } } if $params{$key};
178 my $idx = "${when}/${class}";
179 $hooks{$idx} ||= [ ];
180 push @{ $hooks{$idx} }, { %params, code => $sub };
184 my ($self, $when, $action) = @_;
186 my $idx = "${when}/" . ref($self);
188 foreach my $hook (@{ $hooks{$idx} || [] }) {
189 next if ($hook->{only } && !$hook->{only }->{$action})
190 || ($hook->{except} && $hook->{except}->{$action});
192 if (ref($hook->{code}) eq 'CODE') {
193 $hook->{code}->($self, $action);
195 my $sub = $hook->{code};
196 $self->$sub($action);
202 # behaviour. override these
205 sub delay_flash_on_redirect {
210 # Ignore the 'action' parameter.
214 sub keep_auth_vars_in_form {
219 # private functions -- for use in Base only
225 my $sub = "action_${action}";
227 return $self->_dispatch(@_) if $action eq 'dispatch';
229 $::form->error("Invalid action '${action}' for controller " . ref($self)) if !$self->can($sub);
231 $self->action_name($action);
232 $self->_run_hooks('before', $action);
234 $self->_run_hooks('after', $action);
241 my @actions = map { s/^action_//; $_ } grep { m/^action_/ } keys %{ ref($self) . "::" };
242 my $action = first { $::form->{"action_${_}"} } @actions;
243 my $sub = "action_${action}";
245 if ($self->can($sub)) {
246 $self->action_name($action);
247 $self->_run_hooks('before', $action);
249 $self->_run_hooks('after', $action);
251 $::form->error($::locale->text('Oops. No valid action found to dispatch. Please report this case to the kivitendo team.'));
261 SL::Controller::Base - base class for all action controllers
267 This is a base class for all action controllers. Action controllers
268 provide subs that are callable by special URLs.
270 For each request made to the web server an instance of the controller
271 will be created. After the request has been served that instance will
272 handed over to garbage collection.
274 This base class is derived from L<Rose::Object>.
278 The URLs have the following properties:
284 The script part of the URL must be C<controller.pl>.
288 There must be a GET or POST parameter named C<action> containing the
289 name of the controller and the sub to call separated by C</>,
290 e.g. C<Message/list>.
294 The controller name is the package's name without the
295 C<SL::Controller::> prefix. At the moment only packages in the
296 C<SL::Controller> namespace are valid; sub-namespaces are not
297 allowed. The package name must start with an upper-case letter.
301 The sub part of the C<action> parameter is the name of the sub to
302 call. However, the sub's name is automatically prefixed with
303 C<action_>. Therefore for the example C<Message/list> the sub
304 C<SL::DB::Message::action_list> would be called. This in turn means
305 that subs whose name does not start with C<action_> cannot be invoked
306 directly via the URL.
310 =head2 INDIRECT DISPATCHING
312 In the case that there are several submit buttons on a page it is
313 often impractical to have a single C<action> parameter match up
314 properly. For such a case a special dispatcher method is available. In
315 that case the C<action> parameter of the URL must be
316 C<Controller/dispatch>.
318 The C<SL::Controller::Base::_dispatch> method will iterate over all
319 subs in the controller package whose names start with C<action_>. The
320 first one for which there's a GET or POST parameter with the same name
321 and that's trueish is called.
323 Usage from a template usually looks like this:
325 <form method="POST" action="controller.pl">
327 <input type="hidden" name="action" value="Message/dispatch">
328 <input type="submit" name="action_mark_as_read" value="Mark messages as read">
329 <input type="submit" name="action_delete" value="Delete messages">
332 The dispatching is handled by the function L</_dispatch>.
336 Hooks are functions that are called before or after the controller's
337 action is called. The controller package defines the hooks, and those
338 hooks themselves are run as instance methods.
340 Hooks are run in the order they're added.
342 The hooks receive a single parameter: the name of the action that is
343 about to be called (for C<before> hooks) / was called (for C<after>
346 The return value of the hooks is discarded.
348 Hooks can be defined to run for all actions, for only specific actions
349 or for all actions except a list of actions. Each entry is the action
350 name, not the sub's name. Therefore in order to run a hook before one
351 of the subs C<action_edit> or C<action_save> is called the following
354 __PACKAGE__->run_before('things_to_do_before_edit_and_save', only => [ 'edit', 'save' ]);
358 =head2 PUBLIC HELPER FUNCTIONS
360 These functions are supposed to be called by sub-classed controllers.
364 =item C<render $template, [ $options, ] %locals>
366 Renders the template C<$template>. Provides other variables than
367 C<Form::parse_html_template> does.
369 C<$options>, if present, must be a hash reference. All remaining
370 parameters are slurped into C<%locals>.
372 What is rendered and how C<$template> is interpreted is determined
373 both by C<$template>'s reference type and by the supplied options. The
374 actual rendering is handled by L<SL::Presenter/render>.
376 If C<$template> is a normal scalar (not a reference) then it is meant
377 to be a template file name relative to the C<templates/webpages>
378 directory. The file name to use is determined by the C<type> option.
380 If C<$template> is a reference to a scalar then the referenced
381 scalar's content is used as the content to process. The C<type> option
382 is not considered in this case.
384 C<$template> can also be an instance of L<SL::Presenter::EscapedText>
385 or a reference to such an instance. Both of these cases are handled
386 the same way as if C<$template> were a reference to a scalar: its
387 content is processed, and C<type> is not considered.
389 Other reference types, unknown options and unknown arguments to the
390 C<type> option cause the function to L<croak>.
392 The following options are available (defaults: C<type> = 'html',
393 C<process> = 1, C<output> = 1, C<header> = 1, C<layout> = 1):
399 The template type. Can be C<html> (the default), C<js> for JavaScript
400 or C<json> for JSON content. Affects the extension that's added to the
401 file name given with a non-reference C<$template> argument, the
402 content type HTTP header that is output and whether or not the layout
403 will be output as well (see description of C<layout> below).
407 If trueish (which is also the default) it causes the template/content
408 to be processed by the Template toolkit. Otherwise the
409 template/content is output as-is.
413 If trueish (the default) then the generated output will be sent to the
414 browser in addition to being returned. If falsish then the options
415 C<header> and C<layout> are set to 0 as well.
419 Determines whether or not to output the HTTP response
420 headers. Defaults to the same value that C<output> is set to. If set
421 to falsish then the layout is not output either.
425 Determines whether or not the basic HTML layout structure should be
426 output (HTML header, common JavaScript and stylesheet inclusions, menu
427 etc.). Defaults to 0 if C<type> is not C<html> and to the same value
428 C<header> is set to otherwise.
432 The template itself has access to several variables. These are listed
433 in the documentation to L<SL::Presenter/render>.
435 The function will always return the output.
437 Example: Render a HTML template with a certain title and a few locals
439 $self->render('todo/list',
440 title => 'List TODO items',
441 TODO_ITEMS => SL::DB::Manager::Todo->get_all_sorted);
443 Example: Render a string and return its content for further processing
444 by the calling function. No header is generated due to C<output>.
446 my $content = $self->render(\'[% USE JavaScript %][% JavaScript.replace_with("#someid", "js/something") %]',
449 Example: Render a JavaScript template
450 "templates/webpages/todo/single_item.js" and send it to the
451 browser. Typical use for actions called via AJAX:
453 $self->render('todo/single_item', { type => 'js' },
454 item => $employee->most_important_todo_item);
456 =item C<send_file $file_name, [%params]>
458 Sends the file C<$file_name> to the browser including appropriate HTTP
459 headers for a download. C<%params> can include the following:
463 =item * C<type> -- the file's content type; defaults to
464 'application/octet_stream'
466 =item * C<name> -- the name presented to the browser; defaults to
471 =item C<url_for $url>
473 =item C<url_for $params>
475 =item C<url_for %params>
477 Creates an URL for the given parameters suitable for calling an action
478 controller. If there's only one scalar parameter then it is returned
481 Otherwise the parameters are given either as a single hash ref
482 parameter or as a normal hash.
484 The controller to call is given by C<$params{controller}>. It defaults
485 to the current controller as returned by
488 The action to call is given by C<$params{action}>. It defaults to
491 All other key/value pairs in C<%params> are appended as GET parameters
494 Usage from a template might look like this:
496 <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
498 =item C<redirect_to %url_params>
500 Redirects the browser to a new URL by outputting a HTTP redirect
501 header. The URL is generated by calling L</url_for> with
504 =item C<run_before $sub, %params>
506 =item C<run_after $sub, %params>
508 Adds a hook to run before or after certain actions are run for the
509 current package. The code to run is C<$sub> which is either the name
510 of an instance method or a code reference. If it's the latter then the
511 first parameter will be C<$self>.
513 C<%params> can contain two possible values that restrict the code to
514 be run only for certain actions:
518 =item C<< only => \@list >>
520 Only run the code for actions given in C<@list>. The entries are the
521 action names, not the names of the sub (so it's C<list> instead of
524 =item C<< except => \@list >>
526 Run the code for all actions but for those given in C<@list>. The
527 entries are the action names, not the names of the sub (so it's
528 C<list> instead of C<action_list>).
532 If neither restriction is used then the code will be run for any
535 The hook's return values are discarded.
537 =item C<delay_flash_on_redirect>
539 May be overridden by a controller. If this method returns true, redirect_to
540 will delay all flash messages for the current request. Defaults to false for
541 compatibility reasons.
543 =item C<get_auth_level $action>
545 May be overridden by a controller. Determines what kind of
546 authentication is required for a particular action. Must return either
547 C<admin> (which means that authentication as an admin is required),
548 C<user> (authentication as a normal user suffices) with a possible
549 future value C<none> (which would require no authentication but is not
552 =item C<keep_auth_vars_in_form>
554 May be overridden by a controller. If falsish (the default) all form
555 variables whose name starts with C<{AUTH}> are removed before the
556 request is routed. Only controllers that handle login requests
557 themselves should return trueish for this function.
559 =item C<controller_name>
561 Returns the name of the curernt controller package without the
562 C<SL::Controller::> prefix. This method can be called both as a class
563 method and an instance method.
567 Returns the name of the currently executing action. If the dispatcher
568 mechanism was used then this is not C<dispatch> but the actual method
569 name the dispatching resolved to.
573 Returns the global presenter object by calling
574 L<SL::Presenter/get>.
578 =head2 PRIVATE FUNCTIONS
580 These functions are supposed to be used from this base class only.
586 Implements the method lookup for indirect dispatching mentioned in the
587 section L</INDIRECT DISPATCHING>.
589 =item C<_run_action $action>
591 Executes a sub based on the value of C<$action>. C<$action> is the sub
592 name part of the C<action> GET or POST parameter as described in
595 If C<$action> equals C<dispatch> then the sub L</_dispatch> in this
596 base class is called for L</INDIRECT DISPATCHING>. Otherwise
597 C<$action> is prefixed with C<action_>, and that sub is called on the
598 current controller instance.
604 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>