1 package SL::Controller::Helper::GetModels;
5 use Exporter qw(import);
6 our @EXPORT = qw(get_models_url_params get_callback get_models);
8 use constant PRIV => '__getmodelshelperpriv';
10 my %registered_handlers = ( callback => [], get_models => [] );
12 sub register_get_models_handlers {
13 my ($class, %additional_handlers) = @_;
15 my $only = delete($additional_handlers{ONLY}) || [];
16 $only = [ $only ] if !ref $only;
17 my %hook_params = @{ $only } ? ( only => $only ) : ();
19 $class->run_before(sub { $_[0]->{PRIV()} = { current_action => $_[1] }; }, %hook_params);
21 map { push @{ $registered_handlers{$_} }, $additional_handlers{$_} if $additional_handlers{$_} } keys %registered_handlers;
24 sub get_models_url_params {
25 my ($class, $sub_name_or_code) = @_;
27 my $code = (ref($sub_name_or_code) || '') eq 'CODE' ? $sub_name_or_code : sub { shift->$sub_name_or_code(@_) };
29 my ($self, %params) = @_;
30 my @additional_params = $code->($self);
33 (scalar(@additional_params) == 1) && (ref($additional_params[0]) eq 'HASH') ? %{ $additional_params[0] } : @additional_params,
37 push @{ $registered_handlers{callback} }, $callback;
41 my ($self, %override_params) = @_;
43 my %default_params = _run_handlers($self, 'callback', action => ($self->{PRIV()} || {})->{current_action});
45 return $self->url_for(%default_params, %override_params);
49 my ($self, %override_params) = @_;
51 my %default_params = _run_handlers($self, 'get_models');
53 my %params = (%default_params, %override_params);
54 my $model = delete($params{model}) || die "No 'model' to work on";
56 return "SL::DB::Manager::${model}"->get_all(%params);
60 # private/internal functions
64 my ($self, $handler_type, %params) = @_;
66 foreach my $sub (@{ $registered_handlers{$handler_type} }) {
67 if (ref $sub eq 'CODE') {
68 %params = $sub->($self, %params);
69 } elsif ($self->can($sub)) {
70 %params = $self->$sub(%params);
72 die "SL::Controller::Helper::GetModels::get_callback: Cannot call $sub on " . ref($self) . ")";
88 SL::Controller::Helper::GetModels - Base mixin for controller helpers
89 dealing with semi-automatic handling of sorting and paginating lists
93 For a proper synopsis see L<SL::Controller::Helper::Sorted>.
97 For a generic overview see L<SL::Controller::Helper::Sorted>.
99 This base module is the interface between a controller and specialized
100 helper modules that handle things like sorting and paginating. The
101 specialized helpers register themselves with this module via a call to
102 L<register_get_models_handlers> during compilation time (e.g. in the
103 case of C<Sorted> this happens when the controller calls
104 L<SL::Controller::Helper::Sorted::make_sorted>).
106 A controller will later usually call the L<get_models>
107 function. Templates will call the L<get_callback> function. Both
108 functions run the registered handlers handing over control to the
109 specialized helpers so that they may inject their parameters into the
112 The C<GetModels> helper hooks into the controller call to the action
113 via a C<run_before> hook. This is done so that it can remember the
114 action called by the user. This is used for constructing the callback
117 =head1 PACKAGE FUNCTIONS
121 =item C<get_models_url_params $class, $sub>
123 Register one of the controller's subs to be called whenever an URL has
124 to be generated (e.g. for sort and pagination links). This is a way
125 for the controller to add additional parameters to the URL (e.g. for
128 The C<$sub> parameter can be either a code reference or the name of
129 one of the controller's functions.
131 The value returned by this C<$sub> must be either a single hash
132 reference or a hash of key/value pairs to add to the URL.
134 =item C<register_get_models_handlers $class, %handlers>
136 This function should only be called from other controller helpers like
137 C<Sorted> or C<Paginated>. It is not exported and must therefore be
138 called its full name. The first parameter C<$class> must be the actual
139 controller's class name.
141 If C<%handlers> contains a key C<ONLY> then it is passed to the hook
142 registration in L<SL::Controller::Base::run_before>.
144 The C<%handlers> register callback functions in the specialized
145 controller helpers that are called during invocation of
146 L<get_callback> or L<get_models>. Possible keys are C<callback> and
149 Each handler (the value in the hash) can be either a code reference
150 (in which case it is called directly) or the name of an instance
151 function callable on a controller instance. In both cases the handler
152 receives a hash of parameters built during this very call to
153 L<get_callback> or L<get_models> respectively. The handler's return
154 value must be the new hash to be used in calls to further handlers and
155 to the actual database model functions later on.
159 =head1 INSTANCE FUNCTIONS
163 =item C<get_callback [%params]>
165 Return an URL suitable for use as a callback parameter. It maps to the
166 current controller and action. All registered handlers of type
167 'callback' (e.g. the ones by C<Sorted> and C<Paginated>) can inject
168 the parameters they need so that the same list view as is currently
169 visible can be re-rendered.
171 Optional C<%params> passed to this function may override any parameter
172 set by the registered handlers.
174 =item C<get_models [%params]>
176 Query the model manager via C<get_all> and return its result. The
177 parameters to C<get_all> are constructed by calling all registered
178 handlers of type 'models' (e.g. the ones by C<Sorted> and
181 Optional C<%params> passed to this function may override any parameter
182 set by the registered handlers.
184 The return value is the an array reference of C<Rose> models.
194 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>