projekt kivitendo

SL::Controller::Helper::Filtered - A helper for semi-automatic handling

of filtered lists of database models 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) ],

  );

  sub action_list {

    my ($self) = @_;

    my $filtered_models = $self->get_models(%addition_filters);

    $self->render('controller/list', ENTRIES => $filtered_models);

  }

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>.

C<GetModels>. See the documentation for L<SL::Controller::Sorted> for

=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:

=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>

Optional. Indicates a key in C<$::form> to be used as filter.

Defaults to the values C<filter> if missing.

=item * C<LAUNDER_TO>

Option. Indicates a target for laundered filter arguments in the controller.

Defaults to inplace laundering which is not normally settable.

=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

=head1 INSTANCE FUNCTIONS

These functions are called on a controller instance.

=over 4

=item C<get_current_filter_params>

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.

=item C<disable_filtering>

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.

=head1 BUGS

Nothing here yet.