BackgroundJob models
[kivitendo-erp.git] / SL / Controller / Helper / GetModels.pm
1 package SL::Controller::Helper::GetModels;
2
3 use strict;
4
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;
9
10 use Scalar::Util qw(weaken);
11
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) ],
16 );
17
18 use constant PRIV => '__getmodelshelperpriv';
19
20
21 # official interface
22
23 sub get {
24   my ($self) = @_;
25   my %params = $self->finalize;
26
27   return $self->manager->get_all(%params);
28 }
29
30 sub disable_plugin {
31   my ($self, $plugin) = @_;
32   die 'cannot change internal state after finalize was called' if $self->finalized;
33   die 'unsupported plugin' unless $self->can($plugin) && $self->$plugin && $self->$plugin->isa('SL::Controller::Helper::GetModels::Base');
34
35   $self->$plugin->disabled(1);
36 }
37
38 sub enable_plugin {
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);
43 }
44
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;
49 }
50
51 # TODO: get better delegation
52 sub set_report_generator_sort_options {
53   my ($self, %params) = @_;
54   $self->finalize;
55
56   $self->sorted->set_report_generator_sort_options(%params);
57 }
58
59 sub get_paginate_args {
60   my ($self) = @_;
61   my %params = $self->finalize;
62
63   $self->paginated->get_current_paginate_params(%params);
64 }
65
66 sub get_sort_spec {
67   my ($self) = @_;
68
69   $self->sorted->specs;
70 }
71
72 sub get_current_sort_params {
73   my ($self) = @_;
74
75   $self->sorted->read_params;
76 }
77
78 sub init {
79   my ($self, %params) = @_;
80
81   # TODO: default model
82   $self->model(delete $params{model});
83
84   my @plugins;
85   for my $plugin (qw(filtered sorted paginated)) {
86     next unless my $spec = delete $params{$plugin} // {};
87     my $plugin_class = "SL::Controller::Helper::GetModels::" . ucfirst $plugin;
88     push @plugins, $self->$plugin($plugin_class->new(%$spec, get_models => $self));
89   }
90   $self->plugins(@plugins);
91
92   $self->SUPER::init(%params);
93
94   $_->read_params for $self->plugins;
95
96   weaken $self->controller if $self->controller;
97 }
98
99 sub finalize {
100   my ($self, %params) = @_;
101
102   return %{ $self->final_params } if $self->finalized;
103
104   push @{ $params{query}        ||= [] }, @{ $self->query || [] };
105   push @{ $params{with_objects} ||= [] }, @{ $self->with_objects || [] };
106
107   %params = $_->finalize(%params) for $self->plugins;
108
109   $self->finalized(1);
110   $self->final_params(\%params);
111
112   return %params;
113 }
114
115 sub register_handlers {
116   my ($self, %additional_handlers) = @_;
117
118   my $handlers    = $self->handlers;
119   map { push @{ $handlers->{$_} }, $additional_handlers{$_} if $additional_handlers{$_} } keys %$handlers;
120 }
121
122 # TODO fix this
123 sub get_models_url_params {
124   my ($class, $sub_name_or_code) = @_;
125
126   my $code     = (ref($sub_name_or_code) || '') eq 'CODE' ? $sub_name_or_code : sub { shift->$sub_name_or_code(@_) };
127   my $callback = sub {
128     my ($self, %params)   = @_;
129     my @additional_params = $code->($self);
130     return (
131       %params,
132       (scalar(@additional_params) == 1) && (ref($additional_params[0]) eq 'HASH') ? %{ $additional_params[0] } : @additional_params,
133     );
134   };
135
136   push @{ _registered_handlers($class)->{callback} }, $callback;
137 }
138
139 sub get_callback {
140   my ($self, %override_params) = @_;
141
142   my %default_params = $self->_run_handlers('callback', action => $self->controller->action_name);
143
144   return $self->controller->url_for(%default_params, %override_params);
145 }
146
147 sub manager {
148   die "No 'model' to work on" unless $_[0]->model;
149   "SL::DB::Manager::" . $_[0]->model;
150 }
151
152 #
153 # private/internal functions
154 #
155
156 sub _run_handlers {
157   my ($self, $handler_type, %params) = @_;
158
159   foreach my $sub (@{ $self->handlers->{$handler_type} }) {
160     if (ref $sub eq 'CODE') {
161       %params = $sub->($self, %params);
162     } elsif ($self->can($sub)) {
163       %params = $self->$sub(%params);
164     } else {
165       die "SL::Controller::Helper::GetModels::get_callback: Cannot call $sub on " . ref($self) . ")";
166     }
167   }
168
169   return %params;
170 }
171
172 sub init_handlers {
173   {
174     callback => [],
175   }
176 }
177
178 sub init_source {
179   $::form
180 }
181
182 1;
183 __END__
184
185 =pod
186
187 =encoding utf8
188
189 =head1 NAME
190
191 SL::Controller::Helper::GetModels - Base mixin for controller helpers
192 dealing with semi-automatic handling of sorting and paginating lists
193
194 =head1 SYNOPSIS
195
196 For a proper synopsis see L<SL::Controller::Helper::Sorted>.
197
198 =head1 OVERVIEW
199
200 For a generic overview see L<SL::Controller::Helper::Sorted>.
201
202 This base module is the interface between a controller and specialized
203 helper modules that handle things like sorting and paginating. The
204 specialized helpers register themselves with this module via a call to
205 L<register_get_models_handlers> during compilation time (e.g. in the
206 case of C<Sorted> this happens when the controller calls
207 L<SL::Controller::Helper::Sorted::make_sorted>).
208
209 A controller will later usually call the L<get_models>
210 function. Templates will call the L<get_callback> function. Both
211 functions run the registered handlers handing over control to the
212 specialized helpers so that they may inject their parameters into the
213 call chain.
214
215 The C<GetModels> helper hooks into the controller call to the action
216 via a C<run_before> hook. This is done so that it can remember the
217 action called by the user. This is used for constructing the callback
218 in L<get_callback>.
219
220 =head1 PACKAGE FUNCTIONS
221
222 =over 4
223
224 =item C<get_models_url_params $class, $sub>
225
226 Register one of the controller's subs to be called whenever an URL has
227 to be generated (e.g. for sort and pagination links). This is a way
228 for the controller to add additional parameters to the URL (e.g. for
229 filter parameters).
230
231 The C<$sub> parameter can be either a code reference or the name of
232 one of the controller's functions.
233
234 The value returned by this C<$sub> must be either a single hash
235 reference or a hash of key/value pairs to add to the URL.
236
237 =item C<register_get_models_handlers $class, %handlers>
238
239 This function should only be called from other controller helpers like
240 C<Sorted> or C<Paginated>. It is not exported and must therefore be
241 called its full name. The first parameter C<$class> must be the actual
242 controller's class name.
243
244 If C<%handlers> contains a key C<ONLY> then it is passed to the hook
245 registration in L<SL::Controller::Base::run_before>.
246
247 The C<%handlers> register callback functions in the specialized
248 controller helpers that are called during invocation of
249 L<get_callback> or L<get_models>. Possible keys are C<callback> and
250 C<models>.
251
252 Each handler (the value in the hash) can be either a code reference
253 (in which case it is called directly) or the name of an instance
254 function callable on a controller instance. In both cases the handler
255 receives a hash of parameters built during this very call to
256 L<get_callback> or L<get_models> respectively. The handler's return
257 value must be the new hash to be used in calls to further handlers and
258 to the actual database model functions later on.
259
260 =back
261
262 =head1 INSTANCE FUNCTIONS
263
264 =over 4
265
266 =item C<get_callback [%params]>
267
268 Return an URL suitable for use as a callback parameter. It maps to the
269 current controller and action. All registered handlers of type
270 'callback' (e.g. the ones by C<Sorted> and C<Paginated>) can inject
271 the parameters they need so that the same list view as is currently
272 visible can be re-rendered.
273
274 Optional C<%params> passed to this function may override any parameter
275 set by the registered handlers.
276
277 =item C<get_models [%params]>
278
279 Query the model manager via C<get_all> and return its result. The
280 parameters to C<get_all> are constructed by calling all registered
281 handlers of type 'models' (e.g. the ones by C<Sorted> and
282 C<Paginated>).
283
284 Optional C<%params> passed to this function may override any parameter
285 set by the registered handlers.
286
287 The return value is the an array reference of C<Rose> models.
288
289 =back
290
291 =head1 BUGS
292
293 Nothing here yet.
294
295 =head1 AUTHOR
296
297 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
298
299 =cut