1 package SL::Controller::Helper::GetModels;
5 use parent 'Rose::Object';
6 use SL::Controller::Helper::GetModels::Filtered;
7 use SL::Controller::Helper::GetModels::Sorted;
8 use SL::Controller::Helper::GetModels::Paginated;
10 use Scalar::Util qw(weaken);
12 use Rose::Object::MakeMethods::Generic (
13 scalar => [ qw(controller model query with_objects filtered sorted paginated finalized final_params) ],
14 'scalar --get_set_init' => [ qw(handlers source) ],
15 array => [ qw(plugins) ],
18 use constant PRIV => '__getmodelshelperpriv';
25 my %params = $self->finalize;
26 %params = $self->_run_handlers('get_models', %params);
28 return $self->manager->get_all(%params);
32 my ($self, $plugin) = @_;
33 die 'cannot change internal state after finalize was called' if $self->finalized;
34 die 'unsupported plugin' unless $self->can($plugin) && $self->$plugin && $self->$plugin->isa('SL::Controller::Helper::GetModels::Base');
35 $self->$plugin->disabled(1);
39 my ($self, $plugin) = @_;
40 die 'cannot change internal state after finalize was called' if $self->finalized;
41 die 'unsupported plugin' unless $self->can($plugin) && $self->$plugin && $self->$plugin->isa('SL::Controller::Helper::GetModels::Base');
42 $self->$plugin->disabled(0);
45 sub is_enabled_plugin {
46 my ($self, $plugin) = @_;
47 die 'unsupported plugin' unless $self->can($plugin) && $self->$plugin && $self->$plugin->isa('SL::Controller::Helper::GetModels::Base');
48 $self->$plugin->is_enabled;
51 # TODO: get better delegation
52 sub set_report_generator_sort_options {
53 my ($self, %params) = @_;
56 $self->sorted->set_report_generator_sort_options(%params);
59 sub get_paginate_args {
61 my %params = $self->finalize;
63 $self->paginated->get_current_paginate_params(%params);
67 my ($self, %params) = @_;
70 $self->model(delete $params{model});
73 for my $plugin (qw(filtered sorted paginated)) {
74 next unless my $spec = delete $params{$plugin} // {};
75 my $plugin_class = "SL::Controller::Helper::GetModels::" . ucfirst $plugin;
76 push @plugins, $self->$plugin($plugin_class->new(%$spec, get_models => $self));
78 $self->plugins(@plugins);
80 $self->SUPER::init(%params);
82 $_->read_params for $self->plugins;
84 weaken $self->controller if $self->controller;
88 my ($self, %params) = @_;
90 return %{ $self->final_params } if $self->finalized;
92 push @{ $params{query} ||= [] }, @{ $self->query || [] };
93 push @{ $params{with_objects} ||= [] }, @{ $self->with_objects || [] };
95 %params = $_->finalize(%params) for $self->plugins;
98 $self->final_params(\%params);
103 sub register_handlers {
104 my ($self, %additional_handlers) = @_;
106 my $handlers = $self->handlers;
107 map { push @{ $handlers->{$_} }, $additional_handlers{$_} if $additional_handlers{$_} } keys %$handlers;
111 sub get_models_url_params {
112 my ($class, $sub_name_or_code) = @_;
114 my $code = (ref($sub_name_or_code) || '') eq 'CODE' ? $sub_name_or_code : sub { shift->$sub_name_or_code(@_) };
116 my ($self, %params) = @_;
117 my @additional_params = $code->($self);
120 (scalar(@additional_params) == 1) && (ref($additional_params[0]) eq 'HASH') ? %{ $additional_params[0] } : @additional_params,
124 push @{ _registered_handlers($class)->{callback} }, $callback;
128 my ($self, %override_params) = @_;
130 my %default_params = $self->_run_handlers('callback', action => $self->controller->action_name);
132 return $self->controller->url_for(%default_params, %override_params);
136 die "No 'model' to work on" unless $_[0]->model;
137 "SL::DB::Manager::" . $_[0]->model;
141 # private/internal functions
145 my ($self, $handler_type, %params) = @_;
147 foreach my $sub (@{ $self->handlers->{$handler_type} }) {
148 if (ref $sub eq 'CODE') {
149 %params = $sub->($self, %params);
150 } elsif ($self->can($sub)) {
151 %params = $self->$sub(%params);
153 die "SL::Controller::Helper::GetModels::get_callback: Cannot call $sub on " . ref($self) . ")";
180 SL::Controller::Helper::GetModels - Base mixin for controller helpers
181 dealing with semi-automatic handling of sorting and paginating lists
185 For a proper synopsis see L<SL::Controller::Helper::Sorted>.
189 For a generic overview see L<SL::Controller::Helper::Sorted>.
191 This base module is the interface between a controller and specialized
192 helper modules that handle things like sorting and paginating. The
193 specialized helpers register themselves with this module via a call to
194 L<register_get_models_handlers> during compilation time (e.g. in the
195 case of C<Sorted> this happens when the controller calls
196 L<SL::Controller::Helper::Sorted::make_sorted>).
198 A controller will later usually call the L<get_models>
199 function. Templates will call the L<get_callback> function. Both
200 functions run the registered handlers handing over control to the
201 specialized helpers so that they may inject their parameters into the
204 The C<GetModels> helper hooks into the controller call to the action
205 via a C<run_before> hook. This is done so that it can remember the
206 action called by the user. This is used for constructing the callback
209 =head1 PACKAGE FUNCTIONS
213 =item C<get_models_url_params $class, $sub>
215 Register one of the controller's subs to be called whenever an URL has
216 to be generated (e.g. for sort and pagination links). This is a way
217 for the controller to add additional parameters to the URL (e.g. for
220 The C<$sub> parameter can be either a code reference or the name of
221 one of the controller's functions.
223 The value returned by this C<$sub> must be either a single hash
224 reference or a hash of key/value pairs to add to the URL.
226 =item C<register_get_models_handlers $class, %handlers>
228 This function should only be called from other controller helpers like
229 C<Sorted> or C<Paginated>. It is not exported and must therefore be
230 called its full name. The first parameter C<$class> must be the actual
231 controller's class name.
233 If C<%handlers> contains a key C<ONLY> then it is passed to the hook
234 registration in L<SL::Controller::Base::run_before>.
236 The C<%handlers> register callback functions in the specialized
237 controller helpers that are called during invocation of
238 L<get_callback> or L<get_models>. Possible keys are C<callback> and
241 Each handler (the value in the hash) can be either a code reference
242 (in which case it is called directly) or the name of an instance
243 function callable on a controller instance. In both cases the handler
244 receives a hash of parameters built during this very call to
245 L<get_callback> or L<get_models> respectively. The handler's return
246 value must be the new hash to be used in calls to further handlers and
247 to the actual database model functions later on.
251 =head1 INSTANCE FUNCTIONS
255 =item C<get_callback [%params]>
257 Return an URL suitable for use as a callback parameter. It maps to the
258 current controller and action. All registered handlers of type
259 'callback' (e.g. the ones by C<Sorted> and C<Paginated>) can inject
260 the parameters they need so that the same list view as is currently
261 visible can be re-rendered.
263 Optional C<%params> passed to this function may override any parameter
264 set by the registered handlers.
266 =item C<get_models [%params]>
268 Query the model manager via C<get_all> and return its result. The
269 parameters to C<get_all> are constructed by calling all registered
270 handlers of type 'models' (e.g. the ones by C<Sorted> and
273 Optional C<%params> passed to this function may override any parameter
274 set by the registered handlers.
276 The return value is the an array reference of C<Rose> models.
286 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>