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 Other reference types, unknown options and unknown arguments to the
385 C<type> option cause the function to L<croak>.
387 The following options are available (defaults: C<type> = 'html',
388 C<process> = 1, C<output> = 1, C<header> = 1, C<layout> = 1):
394 The template type. Can be C<html> (the default), C<js> for JavaScript
395 or C<json> for JSON content. Affects the extension that's added to the
396 file name given with a non-reference C<$template> argument, the
397 content type HTTP header that is output and whether or not the layout
398 will be output as well (see description of C<layout> below).
402 If trueish (which is also the default) it causes the template/content
403 to be processed by the Template toolkit. Otherwise the
404 template/content is output as-is.
408 If trueish (the default) then the generated output will be sent to the
409 browser in addition to being returned. If falsish then the options
410 C<header> and C<layout> are set to 0 as well.
414 Determines whether or not to output the HTTP response
415 headers. Defaults to the same value that C<output> is set to. If set
416 to falsish then the layout is not output either.
420 Determines whether or not the basic HTML layout structure should be
421 output (HTML header, common JavaScript and stylesheet inclusions, menu
422 etc.). Defaults to 0 if C<type> is not C<html> and to the same value
423 C<header> is set to otherwise.
427 The template itself has access to several variables. These are listed
428 in the documentation to L<SL::Presenter/render>.
430 The function will always return the output.
432 Example: Render a HTML template with a certain title and a few locals
434 $self->render('todo/list',
435 title => 'List TODO items',
436 TODO_ITEMS => SL::DB::Manager::Todo->get_all_sorted);
438 Example: Render a string and return its content for further processing
439 by the calling function. No header is generated due to C<output>.
441 my $content = $self->render(\'[% USE JavaScript %][% JavaScript.replace_with("#someid", "js/something") %]',
444 Example: Render a JavaScript template
445 "templates/webpages/todo/single_item.js" and send it to the
446 browser. Typical use for actions called via AJAX:
448 $self->render('todo/single_item', { type => 'js' },
449 item => $employee->most_important_todo_item);
451 =item C<send_file $file_name, [%params]>
453 Sends the file C<$file_name> to the browser including appropriate HTTP
454 headers for a download. C<%params> can include the following:
458 =item * C<type> -- the file's content type; defaults to
459 'application/octet_stream'
461 =item * C<name> -- the name presented to the browser; defaults to
466 =item C<url_for $url>
468 =item C<url_for $params>
470 =item C<url_for %params>
472 Creates an URL for the given parameters suitable for calling an action
473 controller. If there's only one scalar parameter then it is returned
476 Otherwise the parameters are given either as a single hash ref
477 parameter or as a normal hash.
479 The controller to call is given by C<$params{controller}>. It defaults
480 to the current controller as returned by
483 The action to call is given by C<$params{action}>. It defaults to
486 All other key/value pairs in C<%params> are appended as GET parameters
489 Usage from a template might look like this:
491 <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
493 =item C<redirect_to %url_params>
495 Redirects the browser to a new URL by outputting a HTTP redirect
496 header. The URL is generated by calling L</url_for> with
499 =item C<run_before $sub, %params>
501 =item C<run_after $sub, %params>
503 Adds a hook to run before or after certain actions are run for the
504 current package. The code to run is C<$sub> which is either the name
505 of an instance method or a code reference. If it's the latter then the
506 first parameter will be C<$self>.
508 C<%params> can contain two possible values that restrict the code to
509 be run only for certain actions:
513 =item C<< only => \@list >>
515 Only run the code for actions given in C<@list>. The entries are the
516 action names, not the names of the sub (so it's C<list> instead of
519 =item C<< except => \@list >>
521 Run the code for all actions but for those given in C<@list>. The
522 entries are the action names, not the names of the sub (so it's
523 C<list> instead of C<action_list>).
527 If neither restriction is used then the code will be run for any
530 The hook's return values are discarded.
532 =item C<delay_flash_on_redirect>
534 May be overridden by a controller. If this method returns true, redirect_to
535 will delay all flash messages for the current request. Defaults to false for
536 compatibility reasons.
538 =item C<get_auth_level $action>
540 May be overridden by a controller. Determines what kind of
541 authentication is required for a particular action. Must return either
542 C<admin> (which means that authentication as an admin is required),
543 C<user> (authentication as a normal user suffices) with a possible
544 future value C<none> (which would require no authentication but is not
547 =item C<keep_auth_vars_in_form>
549 May be overridden by a controller. If falsish (the default) all form
550 variables whose name starts with C<{AUTH}> are removed before the
551 request is routed. Only controllers that handle login requests
552 themselves should return trueish for this function.
554 =item C<controller_name>
556 Returns the name of the curernt controller package without the
557 C<SL::Controller::> prefix. This method can be called both as a class
558 method and an instance method.
562 Returns the name of the currently executing action. If the dispatcher
563 mechanism was used then this is not C<dispatch> but the actual method
564 name the dispatching resolved to.
568 Returns the global presenter object by calling
569 L<SL::Presenter/get>.
573 =head2 PRIVATE FUNCTIONS
575 These functions are supposed to be used from this base class only.
581 Implements the method lookup for indirect dispatching mentioned in the
582 section L</INDIRECT DISPATCHING>.
584 =item C<_run_action $action>
586 Executes a sub based on the value of C<$action>. C<$action> is the sub
587 name part of the C<action> GET or POST parameter as described in
590 If C<$action> equals C<dispatch> then the sub L</_dispatch> in this
591 base class is called for L</INDIRECT DISPATCHING>. Otherwise
592 C<$action> is prefixed with C<action_>, and that sub is called on the
593 current controller instance.
599 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>