1 package SL::Controller::Base;
3 use parent qw(Rose::Object);
5 use List::Util qw(first);
8 # public/helper functions
11 sub parse_html_template {
14 my $locals = shift || {};
16 return $::form->parse_html_template($name, { %{ $locals }, SELF => $self });
22 return $_[0] if (scalar(@_) == 1) && !ref($_[0]);
24 my %params = ref($_[0]) eq 'HASH' ? %{ $_[0] } : @_;
25 my $controller = delete($params{controller}) || $self->_controller_name;
26 my $action = delete($params{action}) || 'dispatch';
27 $params{action} = "${controller}/${action}";
28 my $query = join('&', map { $::form->escape($_) . '=' . $::form->escape($params{$_}) } keys %params);
30 return "controller.pl?${query}";
35 my $url = $self->url_for(@_);
37 print $::cgi->redirect($url);
41 my ($self, $template, %params) = @_;
44 $::form->{title} = delete $params{title};
48 print $self->parse_html_template($template, $params{locals});
52 # private functions -- for use in Base only
57 my $action = "action_" . shift;
59 return $self->_dispatch(@_) if $action eq 'action_dispatch';
61 $::form->error("Invalid action ${action} for controller " . ref($self)) if !$self->can($action);
65 sub _controller_name {
66 return (split(/::/, ref($_[0])))[-1];
72 my @actions = grep { m/^action_/ } keys %{ ref($self) . "::" };
73 my $action = first { $::form->{$_} } @actions;
84 SL::Controller::Base - base class for all action controllers
90 This is a base class for all action controllers. Action controllers
91 provide subs that are callable by special URLs.
93 For each request made to the web server an instance of the controller
94 will be created. After the request has been served that instance will
95 handed over to garbage collection.
97 This base class is derived from L<Rose::Object>.
101 The URLs have the following properties:
107 The script part of the URL must be C<controller.pl>.
111 There must be a GET or POST parameter named C<action> containing the
112 name of the controller and the sub to call separated by C</>,
113 e.g. C<Message/list>.
117 The controller name is the package's name without the
118 C<SL::Controller::> prefix. At the moment only packages in the
119 C<SL::Controller> namespace are valid; sub-namespaces are not
120 allowed. The package name must start with an upper-case letter.
124 The sub part of the C<action> parameter is the name of the sub to
125 call. However, the sub's name is automatically prefixed with
126 C<action_>. Therefore for the example C<Message/list> the sub
127 C<SL::DB::Message::action_list> would be called. This in turn means
128 that subs whose name does not start with C<action_> cannot be invoked
129 directly via the URL.
133 =head2 INDIRECT DISPATCHING
135 In the case that there are several submit buttons on a page it is
136 often impractical to have a single C<action> parameter match up
137 properly. For such a case a special dispatcher method is available. In
138 that case the C<action> parameter of the URL must be
139 C<Controller/dispatch>.
141 The C<SL::Controller::Base::_dispatch> method will iterate over all
142 subs in the controller package whose names start with C<action_>. The
143 first one for which there's a GET or POST parameter with the same name
144 and that's trueish is called.
146 Usage from a template usually looks like this:
148 <form method="POST" action="controller.pl">
150 <input type="hidden" name="action" value="Message/dispatch">
151 <input type="submit" name="action_mark_as_read" value="Mark messages as read">
152 <input type="submit" name="action_delete" value="Delete messages">
155 The dispatching is handled by the function L</_dispatch>.
159 =head2 PUBLIC HELPER FUNCTIONS
161 These functions are supposed to be called by sub-classed controllers.
165 =item C<parse_html_template $file_name, $local_variables>
167 Outputs an HTML template. It is a thin wrapper around
168 C<Form::parse_html_template> which also adds the current object as the
169 template variable C<SELF>.
171 =item C<render $template, %params>
173 Renders the template C<$template> by calling
174 L</parse_html_template>. C<$params{locals}> will be used as the second
175 parameter to L</parse_html_template>.
177 If C<$params{title}> is trueish then the function also sets
178 C<< $::form->{header} >> to that value and calls C<< $::form->header >>.
180 =item C<url_for $url>
182 =item C<url_for $params>
184 =item C<url_for %params>
186 Creates an URL for the given parameters suitable for calling an action
187 controller. If there's only one scalar parameter then it is returned
190 Otherwise the parameters are given either as a single hash ref
191 parameter or as a normal hash.
193 The controller to call is given by C<$params{controller}>. It defaults
194 to the current controller as returned by
195 L</_controller_name>.
197 The action to call is given by C<$params{action}>. It defaults to
200 All other key/value pairs in C<%params> are appended as GET parameters
203 Usage from a template might look like this:
205 <a href="[% SELF.url_for(controller => 'Message', action => 'new', recipient_id => 42) %]">create new message</a>
207 =item redirect_to %url_params
209 Redirects the browser to a new URL by outputting a HTTP redirect
210 header. The URL is generated by calling L</url_for> with
215 =head2 PRIVATE FUNCTIONS
217 These functions are supposed to be used from this base class only.
221 =item C<_controller_name>
223 Returns the name of the curernt controller package without the
224 C<SL::Controller::> prefix.
228 Implements the method lookup for indirect dispatching mentioned in the
229 section L</INDIRECT DISPATCHING>.
231 =item C<_run_action $action>
233 Executes a sub based on the value of C<$action>. C<$action> is the sub
234 name part of the C<action> GET or POST parameter as described in
237 If C<$action> equals C<dispatch> then the sub L</_dispatch> in this
238 base class is called for L</INDIRECT DISPATCHING>. Otherwise
239 C<$action> is prefixed with C<action_>, and that sub is called on the
240 current controller instance.
246 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>