From: Sven Schöling <s.schoeling@linet-services.de>
Date: Tue, 15 Oct 2013 09:26:57 +0000 (+0200)
Subject: Doku
X-Git-Tag: release-3.1.0beta1~35
X-Git-Url: http://wagnertech.de/git?a=commitdiff_plain;h=8a5a3e9c4f991f278171843a6335bcb4724bd03f;p=kivitendo-erp.git

Doku
---

diff --git a/SL/Controller/Helper/GetModels/Filtered.pm b/SL/Controller/Helper/GetModels/Filtered.pm
index 66dd9f6fc..88a298860 100644
--- a/SL/Controller/Helper/GetModels/Filtered.pm
+++ b/SL/Controller/Helper/GetModels/Filtered.pm
@@ -122,126 +122,78 @@ __END__
 
 =head1 NAME
 
-SL::Controller::Helper::Filtered - A helper for semi-automatic handling
-of filtered lists of database models in a controller
+SL::Controller::Helper::GetModels::Filtered - Filter handling plugin for GetModels
 
 =head1 SYNOPSIS
 
 In a controller:
 
-  use SL::Controller::Helper::GetModels;
-  use SL::Controller::Helper::Filtered;
-
-  __PACKAGE__->make_filter(
-    MODEL       => 'Part',
-    ONLY        => [ qw(list) ],
-    FORM_PARAMS => [ qw(filter) ],
-  );
+  SL::Controller::Helper::GetModels->new(
+    ...
+    filtered => {
+      filter      => HASHREF,
+      launder_to  => HASHREF | SUBNAME | '__INPLACE__',
+    }
 
-  sub action_list {
-    my ($self) = @_;
+    OR
 
-    my $filtered_models = $self->get_models(%addition_filters);
-    $self->render('controller/list', ENTRIES => $filtered_models);
-  }
+    filtered => 0,
+  );
 
 
 =head1 OVERVIEW
 
-This helper module enables use of the L<SL::Controller::Helper::ParseFilter>
-methods in conjunction with the L<SL::Controller::Helper::GetModels> style of
-plugins. Additional filters can be defined in the database models and filtering
-can be reduced to a minimum of work.
-
-This plugin can be combined with L<SL::Controller::Sorted> and
-L<SL::Controller::Paginated> for filtered, sorted and paginated lists.
-
-The controller has to provive information where to look for filter information
-at compile time. This call is L<make_filtered>.
+This C<GetModels> plugin enables use of the
+L<SL::Controller::Helper::ParseFilter> methods. Additional filters can be
+defined in the database models and filtering can be reduced to a minimum of
+work.
 
 The underlying functionality that enables the use of more than just
 the paginate helper is provided by the controller helper
-C<GetModels>. See the documentation for L<SL::Controller::Sorted> for
+C<GetModels>. See the documentation for L<SL::Controller::Helper::GetModels> for
 more information on it.
 
-=head1 PACKAGE FUNCTIONS
-
-=over 4
-
-=item C<make_filtered %filter_spec>
-
-This function must be called by a controller at compile time. It is
-uesd to set the various parameters required for this helper to do its
-magic.
-
-Careful: If you want to use this in conjunction with
-L<SL:Controller::Helper::Paginated>, you need to call C<make_filtered> first,
-or the paginating will not get all the relevant information to estimate the
-number of pages correctly. To ensure this does not happen, this module will
-croak when it detects such a scenario.
-
-The hash C<%filter_spec> can include the following parameters:
+=head1 OPTIONS
 
 =over 4
 
-=item * C<MODEL>
-
-Optional. A string: the name of the Rose database model that is used
-as a default in certain cases. If this parameter is missing then it is
-derived from the controller's package (e.g. for the controller
-C<SL::Controller::BackgroundJobHistory> the C<MODEL> would default to
-C<BackgroundJobHistory>).
-
-=item * C<FORM_PARAMS>
+=item * C<filter>
 
-Optional. Indicates a key in C<$::form> to be used as filter.
+Optional. Indicates a key in C<source> to be used as filter.
 
-Defaults to the values C<filter> if missing.
+Defaults to the value C<filter> if missing.
 
-=item * C<LAUNDER_TO>
+=item * C<launder_to>
 
-Option. Indicates a target for laundered filter arguments in the controller.
+Optional. Indicates a target for laundered filter arguments in the controller.
 Can be set to C<undef> to disable laundering, and can be set to method named or
 hash keys of the controller. In the latter case the laundered structure will be
 put there.
 
-Defaults to inplace laundering which is not normally settable.
+Defaults to the controller. Laundered values will end up in C<SELF.filter> for
+template purposes.
 
-=item * C<ONLY>
-
-Optional. An array reference containing a list of action names for
-which the paginate parameters should be saved. If missing or empty then
-all actions invoked on the controller are monitored.
-
-=back
+Setting this to the special value C<__INPLACE__> will cause inplace laundering.
 
 =back
 
-=head1 INSTANCE FUNCTIONS
+=head1 FILTER FORMAT
 
-These functions are called on a controller instance.
+See L<SL::Controller::Helper::ParseFilter> for a description of the filter format.
 
-=over 4
+=head1 CUSTOM FILTERS
 
-=item C<get_current_filter_params>
+C<Filtered> will honor custom filters defined in RDBO managers. See
+L<SL::DB::Helper::Filtered> for an explanation fo those.
 
-Returns a hash to be used in manager C<get_all> calls or to be passed on to
-GetModels. Will only work if the get_models chain has been called at least
-once, because only then the full parameters can get parsed and stored. Will
-croak otherwise.
+=head1 BUGS
 
-=item C<disable_filtering>
+=over 4
 
-Disable filtering for the duration of the current action. Can be used
-when using the attribute C<ONLY> to L<make_filtered> does not
-cover all cases.
+=item * There is currently no easy way to filter for CVars.
 
 =back
 
-=head1 BUGS
-
-Nothing here yet.
-
 =head1 AUTHOR
 
 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>