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