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