1 package SL::Controller::Base;
5 use parent qw(Rose::Object);
8 use List::Util qw(first);
11 # public/helper functions
17 return $_[0] if (scalar(@_) == 1) && !ref($_[0]);
19 my %params = ref($_[0]) eq 'HASH' ? %{ $_[0] } : @_;
20 my $controller = delete($params{controller}) || $self->_controller_name;
21 my $action = delete($params{action}) || 'dispatch';
22 $params{action} = "${controller}/${action}";
23 my $query = join('&', map { $::form->escape($_) . '=' . $::form->escape($params{$_}) } keys %params);
25 return "controller.pl?${query}";
30 my $url = $self->url_for(@_);
32 print $::cgi->redirect($url);
38 my ($options, %locals) = (@_ && ref($_[0])) ? @_ : ({ }, @_);
40 $options->{type} = lc($options->{type} || 'html');
41 $options->{no_layout} = 1 if $options->{type} eq 'js';
44 if ($options->{inline}) {
48 $source = "templates/webpages/${template}." . $options->{type};
49 croak "Template file ${source} not found" unless -f $source;
52 if (!$options->{partial} && !$options->{inline} && !$::form->{header}) {
53 if ($options->{no_layout}) {
54 $::form->{header} = 1;
55 my $content_type = $options->{type} eq 'js' ? 'text/javascript' : 'text/html';
57 print $::form->create_http_response(content_type => $content_type,
58 charset => $::lx_office_conf{system}->{dbcharset} || Common::DEFAULT_CHARSET());
61 $::form->{title} = $locals{title} if $locals{title};
66 my %params = ( %locals,
68 FLASH => $::form->{FLASH},
71 LXCONFIG => \%::lx_office_conf,
72 LXDEBUG => $::lxdebug,
73 MYCONFIG => \%::myconfig,
78 my $parser = $self->_template_obj;
79 $parser->process($source, \%params, \$output) || croak $parser->error;
81 print $output unless $options->{inline} || $options->{no_output};
87 # Before/after run hooks
91 _add_hook('before', @_);
95 _add_hook('after', @_);
101 my ($when, $class, $sub, %params) = @_;
103 foreach my $key (qw(only except)) {
104 $params{$key} = { map { ( $_ => 1 ) } @{ $params{$key} } } if $params{$key};
107 my $idx = "${when}/${class}";
108 $hooks{$idx} ||= [ ];
109 push @{ $hooks{$idx} }, { %params, code => $sub };
113 my ($self, $when, $action) = @_;
115 my $idx = "${when}/" . ref($self);
117 foreach my $hook (@{ $hooks{$idx} || [] }) {
118 next if ($hook->{only } && !$hook->{only }->{$action})
119 || ($hook->{except} && $hook->{except}->{$action});
121 if (ref($hook->{code}) eq 'CODE') {
122 $hook->{code}->($self);
124 my $sub = $hook->{code};
131 # private functions -- for use in Base only
137 my $sub = "action_${action}";
139 return $self->_dispatch(@_) if $action eq 'dispatch';
141 $::form->error("Invalid action '${action}' for controller " . ref($self)) if !$self->can($sub);
143 $self->_run_hooks('before', $action);
145 $self->_run_hooks('after', $action);
148 sub _controller_name {
149 return (split(/::/, ref($_[0])))[-1];
156 my @actions = map { s/^action_//; $_ } grep { m/^action_/ } keys %{ ref($self) . "::" };
157 my $action = first { $::form->{"action_${_}"} } @actions;
158 my $sub = "action_${action}";
160 $self->_run_hooks('before', $action);
162 $self->_run_hooks('after', $action);
168 $self->{__basepriv_template_obj} ||=
169 Template->new({ INTERPOLATE => 0,
173 PLUGIN_BASE => 'SL::Template::Plugin',
174 INCLUDE_PATH => '.:templates/webpages',
175 COMPILE_EXT => '.tcc',
176 COMPILE_DIR => $::lx_office_conf{paths}->{userspath} . '/templates-cache',
179 return $self->{__basepriv_template_obj};
188 SL::Controller::Base - base class for all action controllers
194 This is a base class for all action controllers. Action controllers
195 provide subs that are callable by special URLs.
197 For each request made to the web server an instance of the controller
198 will be created. After the request has been served that instance will
199 handed over to garbage collection.
201 This base class is derived from L<Rose::Object>.
205 The URLs have the following properties:
211 The script part of the URL must be C<controller.pl>.
215 There must be a GET or POST parameter named C<action> containing the
216 name of the controller and the sub to call separated by C</>,
217 e.g. C<Message/list>.
221 The controller name is the package's name without the
222 C<SL::Controller::> prefix. At the moment only packages in the
223 C<SL::Controller> namespace are valid; sub-namespaces are not
224 allowed. The package name must start with an upper-case letter.
228 The sub part of the C<action> parameter is the name of the sub to
229 call. However, the sub's name is automatically prefixed with
230 C<action_>. Therefore for the example C<Message/list> the sub
231 C<SL::DB::Message::action_list> would be called. This in turn means
232 that subs whose name does not start with C<action_> cannot be invoked
233 directly via the URL.
237 =head2 INDIRECT DISPATCHING
239 In the case that there are several submit buttons on a page it is
240 often impractical to have a single C<action> parameter match up
241 properly. For such a case a special dispatcher method is available. In
242 that case the C<action> parameter of the URL must be
243 C<Controller/dispatch>.
245 The C<SL::Controller::Base::_dispatch> method will iterate over all
246 subs in the controller package whose names start with C<action_>. The
247 first one for which there's a GET or POST parameter with the same name
248 and that's trueish is called.
250 Usage from a template usually looks like this:
252 <form method="POST" action="controller.pl">
254 <input type="hidden" name="action" value="Message/dispatch">
255 <input type="submit" name="action_mark_as_read" value="Mark messages as read">
256 <input type="submit" name="action_delete" value="Delete messages">
259 The dispatching is handled by the function L</_dispatch>.
263 Hooks are functions that are called before or after the controller's
264 action is called. The controller package defines the hooks, and those
265 hooks themselves are run as instance methods.
267 Hooks are run in the order they're added.
269 The return value of the hooks is discarded.
271 Hooks can be defined to run for all actions, for only specific actions
272 or for all actions except a list of actions. Each entry is the action
273 name, not the sub's name. Therefore in order to run a hook before one
274 of the subs C<action_edit> or C<action_save> is called the following
277 __PACKAGE__->run_before('things_to_do_before_edit_and_save', only => [ 'edit', 'save' ]);
281 =head2 PUBLIC HELPER FUNCTIONS
283 These functions are supposed to be called by sub-classed controllers.
287 =item C<render $template, [ $options, ] %locals>
289 Renders the template C<$template>. Provides other variables than
290 C<Form::parse_html_template> does.
292 C<$options>, if present, must be a hash reference. All remaining
293 parameters are slurped into C<%locals>.
295 What is rendered and how C<$template> is interpreted is determined by
296 the options I<type>, I<inline>, I<partial> and I<no_layout>.
298 If C<< $options->{inline} >> is trueish then C<$template> is a string
299 containing the template code to interprete. Additionally the output
300 will not be sent to the browser. Instead it is only returned to the
303 If C<< $options->{inline} >> is falsish then C<$template> is
304 interpreted as the name of a template file. It is prefixed with
305 "templates/webpages/" and postfixed with a file extension based on
306 C<< $options->{type} >>. C<< $options->{type} >> can be either C<html>
307 or C<js> and defaults to C<html>. An exception will be thrown if that
310 If C<< $options->{partial} >> or C<< $options->{inline} >> is trueish
311 then neither the HTTP response header nor the standard HTML header is
314 Otherwise at least the HTTP response header will be generated based on
315 the template type (C<< $options->{type} >>).
317 If the template type is C<html> then the standard HTML header will be
318 output via C<< $::form->header >> with C<< $::form->{title} >> set to
319 C<$locals{title}> (the latter only if C<$locals{title}> is
320 trueish). Setting C<< $options->{no_layout} >> to trueish will prevent
323 The template itself has access to the following variables:
327 =item * C<AUTH> -- C<$::auth>
329 =item * C<FORM> -- C<$::form>
331 =item * C<LOCALE> -- C<$::locale>
333 =item * C<LXCONFIG> -- all parameters from C<config/lx_office.conf>
334 with the same name they appear in the file (first level is the
335 section, second the actual variable, e.g. C<system.dbcharset>,
336 C<features.webdav> etc)
338 =item * C<LXDEBUG> -- C<$::lxdebug>
340 =item * C<MYCONFIG> -- C<%::myconfig>
342 =item * C<SELF> -- the controller instance
344 =item * All items from C<%locals>
348 Unless C<< $options->{inline} >> is trueish the function will send the
349 output to the browser.
351 The function will always return the output.
353 Example: Render a HTML template with a certain title and a few locals
355 $self->render('todo/list',
356 title => 'List TODO items',
357 TODO_ITEMS => SL::DB::Manager::Todo->get_all_sorted);
359 Example: Render a string and return its content for further processing
360 by the calling function. No header is generated due to C<inline>.
362 my $content = $self->render('[% USE JavaScript %][% JavaScript.replace_with("#someid", "js/something") %]',
363 { type => 'js', inline => 1 });
365 Example: Render a JavaScript template and send it to the
366 browser. Typical use for actions called via AJAX:
368 $self->render('todo/single_item', { type => 'js' },
369 item => $employee->most_important_todo_item);
371 =item C<url_for $url>
373 =item C<url_for $params>
375 =item C<url_for %params>
377 Creates an URL for the given parameters suitable for calling an action
378 controller. If there's only one scalar parameter then it is returned
381 Otherwise the parameters are given either as a single hash ref
382 parameter or as a normal hash.
384 The controller to call is given by C<$params{controller}>. It defaults
385 to the current controller as returned by
386 L</_controller_name>.
388 The action to call is given by C<$params{action}>. It defaults to
391 All other key/value pairs in C<%params> are appended as GET parameters
394 Usage from a template might look like this:
396 <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
398 =item C<redirect_to %url_params>
400 Redirects the browser to a new URL by outputting a HTTP redirect
401 header. The URL is generated by calling L</url_for> with
404 =item C<run_before $sub, %params>
406 =item C<run_after $sub, %params>
408 Adds a hook to run before or after certain actions are run for the
409 current package. The code to run is C<$sub> which is either the name
410 of an instance method or a code reference. If it's the latter then the
411 first parameter will be C<$self>.
413 C<%params> can contain two possible values that restrict the code to
414 be run only for certain actions:
418 =item C<< only => \@list >>
420 Only run the code for actions given in C<@list>. The entries are the
421 action names, not the names of the sub (so it's C<list> instead of
424 =item C<< except => \@list >>
426 Run the code for all actions but for those given in C<@list>. The
427 entries are the action names, not the names of the sub (so it's
428 C<list> instead of C<action_list>).
432 If neither restriction is used then the code will be run for any
435 The hook's return values are discarded.
439 =head2 PRIVATE FUNCTIONS
441 These functions are supposed to be used from this base class only.
445 =item C<_controller_name>
447 Returns the name of the curernt controller package without the
448 C<SL::Controller::> prefix.
452 Implements the method lookup for indirect dispatching mentioned in the
453 section L</INDIRECT DISPATCHING>.
455 =item C<_run_action $action>
457 Executes a sub based on the value of C<$action>. C<$action> is the sub
458 name part of the C<action> GET or POST parameter as described in
461 If C<$action> equals C<dispatch> then the sub L</_dispatch> in this
462 base class is called for L</INDIRECT DISPATCHING>. Otherwise
463 C<$action> is prefixed with C<action_>, and that sub is called on the
464 current controller instance.
470 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>