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