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