821d7a19424997516397b6af39c3b11023067b82
[kivitendo-erp.git] / SL / Controller / Helper / GetModels.pm
1 package SL::Controller::Helper::GetModels;
2
3 use strict;
4
5 use Exporter qw(import);
6 our @EXPORT = qw(get_models_url_params get_callback get_models);
7
8 use constant PRIV => '__getmodelshelperpriv';
9
10 my $registered_handlers = {};
11
12 sub register_get_models_handlers {
13   my ($class, %additional_handlers) = @_;
14
15   my $only        = delete($additional_handlers{ONLY}) || [];
16   $only           = [ $only ] if !ref $only;
17   my %hook_params = @{ $only } ? ( only => $only ) : ();
18
19   my $handlers    = _registered_handlers($class);
20   map { push @{ $handlers->{$_} }, $additional_handlers{$_} if $additional_handlers{$_} } keys %$handlers;
21 }
22
23 sub get_models_url_params {
24   my ($class, $sub_name_or_code) = @_;
25
26   my $code     = (ref($sub_name_or_code) || '') eq 'CODE' ? $sub_name_or_code : sub { shift->$sub_name_or_code(@_) };
27   my $callback = sub {
28     my ($self, %params)   = @_;
29     my @additional_params = $code->($self);
30     return (
31       %params,
32       (scalar(@additional_params) == 1) && (ref($additional_params[0]) eq 'HASH') ? %{ $additional_params[0] } : @additional_params,
33     );
34   };
35
36   push @{ _registered_handlers($class)->{callback} }, $callback;
37 }
38
39 sub get_callback {
40   my ($self, %override_params) = @_;
41
42   my %default_params = _run_handlers($self, 'callback', action => $self->action_name);
43
44   return $self->url_for(%default_params, %override_params);
45 }
46
47 sub get_models {
48   my ($self, %override_params) = @_;
49
50   my %params                   = _run_handlers($self, 'get_models', %override_params);
51
52   my $model                    = delete($params{model}) || die "No 'model' to work on";
53
54   return "SL::DB::Manager::${model}"->get_all(%params);
55 }
56
57 #
58 # private/internal functions
59 #
60
61 sub _run_handlers {
62   my ($self, $handler_type, %params) = @_;
63
64   foreach my $sub (@{ _registered_handlers(ref $self)->{$handler_type} }) {
65     if (ref $sub eq 'CODE') {
66       %params = $sub->($self, %params);
67     } elsif ($self->can($sub)) {
68       %params = $self->$sub(%params);
69     } else {
70       die "SL::Controller::Helper::GetModels::get_callback: Cannot call $sub on " . ref($self) . ")";
71     }
72   }
73
74   return %params;
75 }
76
77 sub _registered_handlers {
78   $registered_handlers->{$_[0]} //= { callback => [], get_models => [] }
79 }
80
81 1;
82 __END__
83
84 =pod
85
86 =encoding utf8
87
88 =head1 NAME
89
90 SL::Controller::Helper::GetModels - Base mixin for controller helpers
91 dealing with semi-automatic handling of sorting and paginating lists
92
93 =head1 SYNOPSIS
94
95 For a proper synopsis see L<SL::Controller::Helper::Sorted>.
96
97 =head1 OVERVIEW
98
99 For a generic overview see L<SL::Controller::Helper::Sorted>.
100
101 This base module is the interface between a controller and specialized
102 helper modules that handle things like sorting and paginating. The
103 specialized helpers register themselves with this module via a call to
104 L<register_get_models_handlers> during compilation time (e.g. in the
105 case of C<Sorted> this happens when the controller calls
106 L<SL::Controller::Helper::Sorted::make_sorted>).
107
108 A controller will later usually call the L<get_models>
109 function. Templates will call the L<get_callback> function. Both
110 functions run the registered handlers handing over control to the
111 specialized helpers so that they may inject their parameters into the
112 call chain.
113
114 The C<GetModels> helper hooks into the controller call to the action
115 via a C<run_before> hook. This is done so that it can remember the
116 action called by the user. This is used for constructing the callback
117 in L<get_callback>.
118
119 =head1 PACKAGE FUNCTIONS
120
121 =over 4
122
123 =item C<get_models_url_params $class, $sub>
124
125 Register one of the controller's subs to be called whenever an URL has
126 to be generated (e.g. for sort and pagination links). This is a way
127 for the controller to add additional parameters to the URL (e.g. for
128 filter parameters).
129
130 The C<$sub> parameter can be either a code reference or the name of
131 one of the controller's functions.
132
133 The value returned by this C<$sub> must be either a single hash
134 reference or a hash of key/value pairs to add to the URL.
135
136 =item C<register_get_models_handlers $class, %handlers>
137
138 This function should only be called from other controller helpers like
139 C<Sorted> or C<Paginated>. It is not exported and must therefore be
140 called its full name. The first parameter C<$class> must be the actual
141 controller's class name.
142
143 If C<%handlers> contains a key C<ONLY> then it is passed to the hook
144 registration in L<SL::Controller::Base::run_before>.
145
146 The C<%handlers> register callback functions in the specialized
147 controller helpers that are called during invocation of
148 L<get_callback> or L<get_models>. Possible keys are C<callback> and
149 C<models>.
150
151 Each handler (the value in the hash) can be either a code reference
152 (in which case it is called directly) or the name of an instance
153 function callable on a controller instance. In both cases the handler
154 receives a hash of parameters built during this very call to
155 L<get_callback> or L<get_models> respectively. The handler's return
156 value must be the new hash to be used in calls to further handlers and
157 to the actual database model functions later on.
158
159 =back
160
161 =head1 INSTANCE FUNCTIONS
162
163 =over 4
164
165 =item C<get_callback [%params]>
166
167 Return an URL suitable for use as a callback parameter. It maps to the
168 current controller and action. All registered handlers of type
169 'callback' (e.g. the ones by C<Sorted> and C<Paginated>) can inject
170 the parameters they need so that the same list view as is currently
171 visible can be re-rendered.
172
173 Optional C<%params> passed to this function may override any parameter
174 set by the registered handlers.
175
176 =item C<get_models [%params]>
177
178 Query the model manager via C<get_all> and return its result. The
179 parameters to C<get_all> are constructed by calling all registered
180 handlers of type 'models' (e.g. the ones by C<Sorted> and
181 C<Paginated>).
182
183 Optional C<%params> passed to this function may override any parameter
184 set by the registered handlers.
185
186 The return value is the an array reference of C<Rose> models.
187
188 =back
189
190 =head1 BUGS
191
192 Nothing here yet.
193
194 =head1 AUTHOR
195
196 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
197
198 =cut