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