1 package SL::Controller::Base;
5 use parent qw(Rose::Object);
9 use List::Util qw(first);
12 # public/helper functions
18 return $_[0] if (scalar(@_) == 1) && !ref($_[0]);
20 my %params = ref($_[0]) eq 'HASH' ? %{ $_[0] } : @_;
21 my $controller = delete($params{controller}) || $self->_controller_name;
22 my $action = delete($params{action}) || 'dispatch';
23 $params{action} = "${controller}/${action}";
24 my $query = join('&', map { $::form->escape($_) . '=' . $::form->escape($params{$_}) } keys %params);
26 return "controller.pl?${query}";
31 my $url = $self->url_for(@_);
33 print $::cgi->redirect($url);
39 my ($options, %locals) = (@_ && ref($_[0])) ? @_ : ({ }, @_);
41 $options->{type} = lc($options->{type} || 'html');
42 $options->{no_layout} = 1 if $options->{type} eq 'js';
45 if ($options->{inline}) {
48 } elsif($options->{raw}) {
52 $source = "templates/webpages/${template}." . $options->{type};
53 croak "Template file ${source} not found" unless -f $source;
56 if (!$options->{partial} && !$options->{inline} && !$::form->{header}) {
57 if ($options->{no_layout}) {
58 $::form->{header} = 1;
59 my $content_type = $options->{type} eq 'js' ? 'text/javascript' : 'text/html';
61 print $::form->create_http_response(content_type => $content_type,
62 charset => $::lx_office_conf{system}->{dbcharset} || Common::DEFAULT_CHARSET());
65 $::form->{title} = $locals{title} if $locals{title};
70 my %params = ( %locals,
72 FLASH => $::form->{FLASH},
74 INSTANCE_CONF => $::instance_conf,
76 LXCONFIG => \%::lx_office_conf,
77 LXDEBUG => $::lxdebug,
78 MYCONFIG => \%::myconfig,
83 if (!$options->{raw}) {
84 my $parser = $self->_template_obj;
85 $parser->process($source, \%params, \$output) || croak $parser->error;
90 print $output unless $options->{inline} || $options->{no_output};
96 my ($self, $file_name, %params) = @_;
98 my $file = IO::File->new($file_name, 'r') || croak("Cannot open file '${file_name}'");
99 my $content_type = $params{type} || 'application/octet_stream';
100 my $attachment_name = $params{name} || $file_name;
101 $attachment_name =~ s:.*//::g;
103 print $::form->create_http_response(content_type => $content_type,
104 content_disposition => 'attachment; filename="' . $attachment_name . '"',
105 content_length => -s $file);
107 $::locale->with_raw_io(\*STDOUT, sub { print while <$file> });
112 # Before/after run hooks
116 _add_hook('before', @_);
120 _add_hook('after', @_);
126 my ($when, $class, $sub, %params) = @_;
128 foreach my $key (qw(only except)) {
129 $params{$key} = { map { ( $_ => 1 ) } @{ $params{$key} } } if $params{$key};
132 my $idx = "${when}/${class}";
133 $hooks{$idx} ||= [ ];
134 push @{ $hooks{$idx} }, { %params, code => $sub };
138 my ($self, $when, $action) = @_;
140 my $idx = "${when}/" . ref($self);
142 foreach my $hook (@{ $hooks{$idx} || [] }) {
143 next if ($hook->{only } && !$hook->{only }->{$action})
144 || ($hook->{except} && $hook->{except}->{$action});
146 if (ref($hook->{code}) eq 'CODE') {
147 $hook->{code}->($self);
149 my $sub = $hook->{code};
156 # private functions -- for use in Base only
162 my $sub = "action_${action}";
164 return $self->_dispatch(@_) if $action eq 'dispatch';
166 $::form->error("Invalid action '${action}' for controller " . ref($self)) if !$self->can($sub);
168 $self->_run_hooks('before', $action);
170 $self->_run_hooks('after', $action);
173 sub _controller_name {
174 return (split(/::/, ref($_[0])))[-1];
181 my @actions = map { s/^action_//; $_ } grep { m/^action_/ } keys %{ ref($self) . "::" };
182 my $action = first { $::form->{"action_${_}"} } @actions;
183 my $sub = "action_${action}";
185 if ($self->can($sub)) {
186 $self->_run_hooks('before', $action);
188 $self->_run_hooks('after', $action);
190 $::form->error($::locale->text('Oops. No valid action found to dispatch. Please report this case to the Lx-Office team.'));
197 $self->{__basepriv_template_obj} ||=
198 Template->new({ INTERPOLATE => 0,
202 PLUGIN_BASE => 'SL::Template::Plugin',
203 INCLUDE_PATH => '.:templates/webpages',
204 COMPILE_EXT => '.tcc',
205 COMPILE_DIR => $::lx_office_conf{paths}->{userspath} . '/templates-cache',
208 return $self->{__basepriv_template_obj};
217 SL::Controller::Base - base class for all action controllers
223 This is a base class for all action controllers. Action controllers
224 provide subs that are callable by special URLs.
226 For each request made to the web server an instance of the controller
227 will be created. After the request has been served that instance will
228 handed over to garbage collection.
230 This base class is derived from L<Rose::Object>.
234 The URLs have the following properties:
240 The script part of the URL must be C<controller.pl>.
244 There must be a GET or POST parameter named C<action> containing the
245 name of the controller and the sub to call separated by C</>,
246 e.g. C<Message/list>.
250 The controller name is the package's name without the
251 C<SL::Controller::> prefix. At the moment only packages in the
252 C<SL::Controller> namespace are valid; sub-namespaces are not
253 allowed. The package name must start with an upper-case letter.
257 The sub part of the C<action> parameter is the name of the sub to
258 call. However, the sub's name is automatically prefixed with
259 C<action_>. Therefore for the example C<Message/list> the sub
260 C<SL::DB::Message::action_list> would be called. This in turn means
261 that subs whose name does not start with C<action_> cannot be invoked
262 directly via the URL.
266 =head2 INDIRECT DISPATCHING
268 In the case that there are several submit buttons on a page it is
269 often impractical to have a single C<action> parameter match up
270 properly. For such a case a special dispatcher method is available. In
271 that case the C<action> parameter of the URL must be
272 C<Controller/dispatch>.
274 The C<SL::Controller::Base::_dispatch> method will iterate over all
275 subs in the controller package whose names start with C<action_>. The
276 first one for which there's a GET or POST parameter with the same name
277 and that's trueish is called.
279 Usage from a template usually looks like this:
281 <form method="POST" action="controller.pl">
283 <input type="hidden" name="action" value="Message/dispatch">
284 <input type="submit" name="action_mark_as_read" value="Mark messages as read">
285 <input type="submit" name="action_delete" value="Delete messages">
288 The dispatching is handled by the function L</_dispatch>.
292 Hooks are functions that are called before or after the controller's
293 action is called. The controller package defines the hooks, and those
294 hooks themselves are run as instance methods.
296 Hooks are run in the order they're added.
298 The return value of the hooks is discarded.
300 Hooks can be defined to run for all actions, for only specific actions
301 or for all actions except a list of actions. Each entry is the action
302 name, not the sub's name. Therefore in order to run a hook before one
303 of the subs C<action_edit> or C<action_save> is called the following
306 __PACKAGE__->run_before('things_to_do_before_edit_and_save', only => [ 'edit', 'save' ]);
310 =head2 PUBLIC HELPER FUNCTIONS
312 These functions are supposed to be called by sub-classed controllers.
316 =item C<render $template, [ $options, ] %locals>
318 Renders the template C<$template>. Provides other variables than
319 C<Form::parse_html_template> does.
321 C<$options>, if present, must be a hash reference. All remaining
322 parameters are slurped into C<%locals>.
324 What is rendered and how C<$template> is interpreted is determined by
325 the options I<type>, I<inline>, I<partial> and I<no_layout>.
327 If C<< $options->{inline} >> is trueish then C<$template> is a string
328 containing the template code to interprete. Additionally the output
329 will not be sent to the browser. Instead it is only returned to the
332 If C<< $options->{raw}>> is trueish, the function will treat the input as
333 already parsed, and will not filter the input through Template. Unlike
334 C<inline>, the input is taked as a reference.
336 If C<< $options->{inline} >> is falsish then C<$template> is
337 interpreted as the name of a template file. It is prefixed with
338 "templates/webpages/" and postfixed with a file extension based on
339 C<< $options->{type} >>. C<< $options->{type} >> can be either C<html>
340 or C<js> and defaults to C<html>. An exception will be thrown if that
343 If C<< $options->{partial} >> or C<< $options->{inline} >> is trueish
344 then neither the HTTP response header nor the standard HTML header is
347 Otherwise at least the HTTP response header will be generated based on
348 the template type (C<< $options->{type} >>).
350 If the template type is C<html> then the standard HTML header will be
351 output via C<< $::form->header >> with C<< $::form->{title} >> set to
352 C<$locals{title}> (the latter only if C<$locals{title}> is
353 trueish). Setting C<< $options->{no_layout} >> to trueish will prevent
356 The template itself has access to the following variables:
360 =item * C<AUTH> -- C<$::auth>
362 =item * C<FORM> -- C<$::form>
364 =item * C<LOCALE> -- C<$::locale>
366 =item * C<LXCONFIG> -- all parameters from C<config/lx_office.conf>
367 with the same name they appear in the file (first level is the
368 section, second the actual variable, e.g. C<system.dbcharset>,
369 C<features.webdav> etc)
371 =item * C<LXDEBUG> -- C<$::lxdebug>
373 =item * C<MYCONFIG> -- C<%::myconfig>
375 =item * C<SELF> -- the controller instance
377 =item * All items from C<%locals>
381 Unless C<< $options->{inline} >> is trueish the function will send the
382 output to the browser.
384 The function will always return the output.
386 Example: Render a HTML template with a certain title and a few locals
388 $self->render('todo/list',
389 title => 'List TODO items',
390 TODO_ITEMS => SL::DB::Manager::Todo->get_all_sorted);
392 Example: Render a string and return its content for further processing
393 by the calling function. No header is generated due to C<inline>.
395 my $content = $self->render('[% USE JavaScript %][% JavaScript.replace_with("#someid", "js/something") %]',
396 { type => 'js', inline => 1 });
398 Example: Render a JavaScript template and send it to the
399 browser. Typical use for actions called via AJAX:
401 $self->render('todo/single_item', { type => 'js' },
402 item => $employee->most_important_todo_item);
404 =item C<send_file $file_name, [%params]>
406 Sends the file C<$file_name> to the browser including appropriate HTTP
407 headers for a download. C<%params> can include the following:
411 =item * C<type> -- the file's content type; defaults to
412 'application/octet_stream'
414 =item * C<name> -- the name presented to the browser; defaults to
419 =item C<url_for $url>
421 =item C<url_for $params>
423 =item C<url_for %params>
425 Creates an URL for the given parameters suitable for calling an action
426 controller. If there's only one scalar parameter then it is returned
429 Otherwise the parameters are given either as a single hash ref
430 parameter or as a normal hash.
432 The controller to call is given by C<$params{controller}>. It defaults
433 to the current controller as returned by
434 L</_controller_name>.
436 The action to call is given by C<$params{action}>. It defaults to
439 All other key/value pairs in C<%params> are appended as GET parameters
442 Usage from a template might look like this:
444 <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
446 =item C<redirect_to %url_params>
448 Redirects the browser to a new URL by outputting a HTTP redirect
449 header. The URL is generated by calling L</url_for> with
452 =item C<run_before $sub, %params>
454 =item C<run_after $sub, %params>
456 Adds a hook to run before or after certain actions are run for the
457 current package. The code to run is C<$sub> which is either the name
458 of an instance method or a code reference. If it's the latter then the
459 first parameter will be C<$self>.
461 C<%params> can contain two possible values that restrict the code to
462 be run only for certain actions:
466 =item C<< only => \@list >>
468 Only run the code for actions given in C<@list>. The entries are the
469 action names, not the names of the sub (so it's C<list> instead of
472 =item C<< except => \@list >>
474 Run the code for all actions but for those given in C<@list>. The
475 entries are the action names, not the names of the sub (so it's
476 C<list> instead of C<action_list>).
480 If neither restriction is used then the code will be run for any
483 The hook's return values are discarded.
487 =head2 PRIVATE FUNCTIONS
489 These functions are supposed to be used from this base class only.
493 =item C<_controller_name>
495 Returns the name of the curernt controller package without the
496 C<SL::Controller::> prefix.
500 Implements the method lookup for indirect dispatching mentioned in the
501 section L</INDIRECT DISPATCHING>.
503 =item C<_run_action $action>
505 Executes a sub based on the value of C<$action>. C<$action> is the sub
506 name part of the C<action> GET or POST parameter as described in
509 If C<$action> equals C<dispatch> then the sub L</_dispatch> in this
510 base class is called for L</INDIRECT DISPATCHING>. Otherwise
511 C<$action> is prefixed with C<action_>, and that sub is called on the
512 current controller instance.
518 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>