projekt kivitendo

  use SL::Controller::Helper::GetModels;

  use SL::Controller::Helper::Paginated;

  __PACKAGE__->make_paginated(

    MODEL       => 'BackgroundJobHistory',

    ONLY        => [ qw(list) ],

    FORM_PARAMS => [ qw(page per_page) ],

  sub action_list {

    my ($self) = @_;

    my $paginated_models = $self->get_models;

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

  }

  [% USE L %]

  <table>

   <thead>

    <tr>

     ...

    </tr>

   </thead>

   <tbody>

    [% FOREACH entry = ENTRIES %]

     <tr>

      ...

     </tr>

    [% END %]

   </tbody>

  </table>

This specialized helper module enables controllers to display a

paginatable list of database models with as few lines as possible. It

can also be combined trivially with the L<SL::Controller::Sorted>

helper for sortable lists.

indexes are eligible for paginateing etc. by a call to

L<make_paginated> at compile time.

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

more information on it.

The C<Paginated> helper hooks into the controller call to the action via

a C<run_before> hook. This is done so that it can remember the paginate

parameters that were used in the current view.

=head1 PACKAGE FUNCTIONS

=item C<make_paginated %paginate_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.

The hash C<%paginate_spec> can include the following parameters:

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

Optional. Either a code reference or the name of function to be called

on the controller importing this helper.

If this funciton is given then the paginate helper calls it whenever

it has to count the total number of models for calculating the number

of pages to display. The function must return a hash reference with

elements suitable for passing to a Rose model manager's C<get_all>

function.

This can be used e.g. when filtering is used.

=item * C<PER_PAGE>

Optional. An integer: the number of models to return per page.

=item * C<FORM_PARAMS>

=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

These functions are called on a controller instance.

Returns a hash reference to the paginate spec structure given in the call

to L<make_paginated> after normalization (hash reference construction,

=item C<disable_pagination>

Disable pagination for the duration of the current action. Can be used

when using the attribute C<ONLY> to L<make_paginated> does not

cover all cases.

Nothing here yet.

  use SL::Controller::Helper::GetModels;

  use SL::Controller::Helper::Sorted;

  __PACKAGE__->make_sorted(                                     # update this

    DEFAULT_BY   => 'run_at',

    DEFAULT_DIR  => 1,

    MODEL        => 'BackgroundJobHistory',

    ONLY         => [ qw(list) ],

    error        => $::locale->text('Error'),

    package_name => $::locale->text('Package name'),

    run_at       => $::locale->text('Run at'),

  sub action_list {

    my ($self) = @_;

    my $sorted_models = $self->get_models;

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

  }

In said template:

    <th>[% L.sortable_table_header('package_name') %]</th>         # models

This specialized helper module enables controllers to display a

indexes are eligible for sorting etc. by a call to L<make_sorted> at  #not compiletime

compile time.

The underlying functionality that enables the use of more than just

the sort helper is provided by the controller helper C<GetModels>. It

provides mechanisms for helpers like this one to hook into certain

calls made by the controller (C<get_callback> and C<get_models>) so

that the specialized helpers can inject their parameters into the

calls to e.g. C<SL::DB::Manager::SomeModel::get_all>.

A template on the other hand can use the method

C<sortable_table_header> from the layout helper module C<L>.

This module requires that the Rose model managers use their C<Sorted>

helper.

The C<Sorted> helper hooks into the controller call to the action via

a C<run_before> hook. This is done so that it can remember the sort

parameters that were used in the current view.

=head1 PACKAGE FUNCTIONS

=item C<make_sorted %sort_spec>                                         # meh complete rewrite

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.

There are two sorts of keys in the hash C<%sort_spec>. The first kind

is written in all upper-case. Those parameters are control

parameters. The second kind are all lower-case and represent indexes

that can be used for sorting (similar to database column names). The

second kind are also the indexes you use in a template when calling

C<[% L.sorted_table_header(...) %]>.

Control parameters include the following:

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

Optional. A string: the index to sort by if the user hasn't clicked on

any column yet (meaning: if the C<$::form> parameters for sorting do

not contain a valid index).

Defaults to the underlying database model's default sort column name.

=item * C<DEFAULT_DIR>

Optional. Default sort direction (ascending for trueish values,

descrending for falsish values).

Defaults to the underlying database model's default sort direction.

=item * C<FORM_PARAMS>

indexes in C<$::form> in which the sort index (the first element in

=item * C<ONLY>

Optional. An array reference containing a list of action names for

which the sort parameters should be saved. If missing or empty then

all actions invoked on the controller are monitored.

All keys that are written in all lower-case name indexes that can be

used for sorting. Each value to such a key can be either a string or a

hash reference containing certain elements. If the value is only a

string then such a hash reference is constructed, and the string is

These functions are called on a controller instance.

C<%sort_spec> given to L<make_sorted>.

Returns a hash reference to the sort spec structure given in the call

to L<make_sorted> after normalization (hash reference construction,

applying default parameters etc).

=item 3. it adds the C<FORM_PARAMS> fields to the list of variables in