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])) ? @_ : ({ }, @_);
41 if ($options->{inline}) {
45 $source = "templates/webpages/${template}.html";
46 croak "Template file ${source} not found" unless -f $source;
49 if (!$options->{partial} && !$options->{inline}) {
50 $::form->{title} = $locals{title} if $locals{title};
54 my %params = ( %locals,
58 LXCONFIG => { dbcharset => $::dbcharset,
60 lizenzen => $::lizenzen,
61 latex_templates => $::latex,
62 opendocument_templates => $::opendocument_templates,
63 vertreter => $::vertreter,
64 show_best_before => $::show_best_before,
66 LXDEBUG => $::lxdebug,
67 MYCONFIG => \%::myconfig,
72 my $parser = $self->_template_obj;
73 $parser->process($source, \%params, \$output) || croak $parser->error;
75 print $output unless $options->{inline};
81 # Before/after run hooks
85 _add_hook('before', @_);
89 _add_hook('after', @_);
95 my ($when, $class, $sub, %params) = @_;
97 foreach my $key (qw(only except)) {
98 $params{$key} = { map { ( $_ => 1 ) } @{ $params{$key} } } if $params{$key};
101 my $idx = "${when}/${class}";
102 $hooks{$idx} ||= [ ];
103 push @{ $hooks{$idx} }, { %params, code => $sub };
107 my ($self, $when, $action) = @_;
109 my $idx = "${when}/" . ref($self);
111 foreach my $hook (@{ $hooks{$idx} || [] }) {
112 next if ($hook->{only } && !$hook->{only }->{$action})
113 || ($hook->{except} && $hook->{except}->{$action});
115 if (ref($hook->{code}) eq 'CODE') {
116 $hook->{code}->($self);
118 my $sub = $hook->{code};
125 # private functions -- for use in Base only
131 my $sub = "action_${action}";
133 return $self->_dispatch(@_) if $action eq 'dispatch';
135 $::form->error("Invalid action '${action}' for controller " . ref($self)) if !$self->can($sub);
137 $self->_run_hooks('before', $action);
139 $self->_run_hooks('after', $action);
142 sub _controller_name {
143 return (split(/::/, ref($_[0])))[-1];
150 my @actions = map { s/^action_//; $_ } grep { m/^action_/ } keys %{ ref($self) . "::" };
151 my $action = first { $::form->{"action_${_}"} } @actions;
152 my $sub = "action_${action}";
154 $self->_run_hooks('before', $action);
156 $self->_run_hooks('after', $action);
162 $self->{__basepriv_template_obj} ||=
163 Template->new({ INTERPOLATE => 0,
167 PLUGIN_BASE => 'SL::Template::Plugin',
168 INCLUDE_PATH => '.:templates/webpages',
169 COMPILE_EXT => '.tcc',
170 COMPILE_DIR => $::userspath . '/templates-cache',
173 return $self->{__basepriv_template_obj};
182 SL::Controller::Base - base class for all action controllers
188 This is a base class for all action controllers. Action controllers
189 provide subs that are callable by special URLs.
191 For each request made to the web server an instance of the controller
192 will be created. After the request has been served that instance will
193 handed over to garbage collection.
195 This base class is derived from L<Rose::Object>.
199 The URLs have the following properties:
205 The script part of the URL must be C<controller.pl>.
209 There must be a GET or POST parameter named C<action> containing the
210 name of the controller and the sub to call separated by C</>,
211 e.g. C<Message/list>.
215 The controller name is the package's name without the
216 C<SL::Controller::> prefix. At the moment only packages in the
217 C<SL::Controller> namespace are valid; sub-namespaces are not
218 allowed. The package name must start with an upper-case letter.
222 The sub part of the C<action> parameter is the name of the sub to
223 call. However, the sub's name is automatically prefixed with
224 C<action_>. Therefore for the example C<Message/list> the sub
225 C<SL::DB::Message::action_list> would be called. This in turn means
226 that subs whose name does not start with C<action_> cannot be invoked
227 directly via the URL.
231 =head2 INDIRECT DISPATCHING
233 In the case that there are several submit buttons on a page it is
234 often impractical to have a single C<action> parameter match up
235 properly. For such a case a special dispatcher method is available. In
236 that case the C<action> parameter of the URL must be
237 C<Controller/dispatch>.
239 The C<SL::Controller::Base::_dispatch> method will iterate over all
240 subs in the controller package whose names start with C<action_>. The
241 first one for which there's a GET or POST parameter with the same name
242 and that's trueish is called.
244 Usage from a template usually looks like this:
246 <form method="POST" action="controller.pl">
248 <input type="hidden" name="action" value="Message/dispatch">
249 <input type="submit" name="action_mark_as_read" value="Mark messages as read">
250 <input type="submit" name="action_delete" value="Delete messages">
253 The dispatching is handled by the function L</_dispatch>.
257 Hooks are functions that are called before or after the controller's
258 action is called. The controller package defines the hooks, and those
259 hooks themselves are run as instance methods.
261 Hooks are run in the order they're added.
263 The return value of the hooks is discarded.
265 Hooks can be defined to run for all actions, for only specific actions
266 or for all actions except a list of actions. Each entry is the action
267 name, not the sub's name. Therefore in order to run a hook before one
268 of the subs C<action_edit> or C<action_save> is called the following
271 __PACKAGE__->run_before('things_to_do_before_edit_and_save', only => [ 'edit', 'save' ]);
275 =head2 PUBLIC HELPER FUNCTIONS
277 These functions are supposed to be called by sub-classed controllers.
281 =item C<render $template, [ $options, ] %locals>
283 Renders the template C<$template>. Provides other variables than
284 C<Form::parse_html_template> does.
286 C<$options>, if present, must be a hash reference. All remaining
287 parameters are slurped into C<%locals>.
289 What is rendered and how C<$template> is interpreted is determined by
290 C<< $options->{inline} >> and C<< $options->{partial} >>.
292 If C<< $options->{inline} >> is trueish then C<$template> is a string
293 containing the template code to interprete. Additionally the output
294 will not be sent to the browser. Instead it is only returned to the
297 If C<< $options->{inline} >> is falsish then C<$template> is
298 interpreted as the name of a template file. It is prefixed with
299 "templates/webpages/" and postfixed with ".html". An exception will be
300 thrown if that file does not exist.
302 If C<< $options->{partial} >> or C<< $options->{inline} >> is trueish
303 then C<< $::form->header >> will not be called. Otherwise
304 C<< $::form->{header} >> will be set to C<$locals{header}> (only if
305 $locals{header} is trueish) and C<< $::form->header >> will be called
306 before the template itself is processed.
308 The template itself has access to the following variables:
312 =item * C<AUTH> -- C<$::auth>
314 =item * C<FORM> -- C<$::form>
316 =item * C<LOCALE> -- C<$::locale>
318 =item * C<LXCONFIG> -- all parameters from C<config/lx-erp.conf> with
319 the same name they appear in the file (e.g. C<dbcharset>, C<webdav>
322 =item * C<LXDEBUG> -- C<$::lxdebug>
324 =item * C<MYCONFIG> -- C<%::myconfig>
326 =item * C<SELF> -- the controller instance
328 =item * All items from C<%locals>
332 Unless C<< $options->{inline} >> is trueish the function will send the
333 output to the browser.
335 The function will always return the output.
337 =item C<url_for $url>
339 =item C<url_for $params>
341 =item C<url_for %params>
343 Creates an URL for the given parameters suitable for calling an action
344 controller. If there's only one scalar parameter then it is returned
347 Otherwise the parameters are given either as a single hash ref
348 parameter or as a normal hash.
350 The controller to call is given by C<$params{controller}>. It defaults
351 to the current controller as returned by
352 L</_controller_name>.
354 The action to call is given by C<$params{action}>. It defaults to
357 All other key/value pairs in C<%params> are appended as GET parameters
360 Usage from a template might look like this:
362 <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
364 =item C<redirect_to %url_params>
366 Redirects the browser to a new URL by outputting a HTTP redirect
367 header. The URL is generated by calling L</url_for> with
370 =item C<run_before $sub, %params>
372 =item C<run_after $sub, %params>
374 Adds a hook to run before or after certain actions are run for the
375 current package. The code to run is C<$sub> which is either the name
376 of an instance method or a code reference. If it's the latter then the
377 first parameter will be C<$self>.
379 C<%params> can contain two possible values that restrict the code to
380 be run only for certain actions:
384 =item C<< only => \@list >>
386 Only run the code for actions given in C<@list>. The entries are the
387 action names, not the names of the sub (so it's C<list> instead of
390 =item C<< except => \@list >>
392 Run the code for all actions but for those given in C<@list>. The
393 entries are the action names, not the names of the sub (so it's
394 C<list> instead of C<action_list>).
398 If neither restriction is used then the code will be run for any
401 The hook's return values are discarded.
405 =head2 PRIVATE FUNCTIONS
407 These functions are supposed to be used from this base class only.
411 =item C<_controller_name>
413 Returns the name of the curernt controller package without the
414 C<SL::Controller::> prefix.
418 Implements the method lookup for indirect dispatching mentioned in the
419 section L</INDIRECT DISPATCHING>.
421 =item C<_run_action $action>
423 Executes a sub based on the value of C<$action>. C<$action> is the sub
424 name part of the C<action> GET or POST parameter as described in
427 If C<$action> equals C<dispatch> then the sub L</_dispatch> in this
428 base class is called for L</INDIRECT DISPATCHING>. Otherwise
429 C<$action> is prefixed with C<action_>, and that sub is called on the
430 current controller instance.
436 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>