projekt kivitendo

  'scalar --get_set_init' => [ qw(models) ],

#__PACKAGE__->make_filtered(

#  MODEL             => 'OrderItem',

#  LAUNDER_TO        => 'filter'

#);

#__PACKAGE__->make_paginated(

#  MODEL         => 'OrderItem',

#  ONLY          => [ qw(list) ],

#);

#

#__PACKAGE__->make_sorted(

#  MODEL             => 'OrderItem',

#  ONLY              => [ qw(list) ],

#

#  DEFAULT_BY        => 'reqdate',

#  DEFAULT_DIR       => 1,

#

#  reqdate           => t8('Reqdate'),

#  description       => t8('Description'),

#  partnumber        => t8('Part Number'),

#  qty               => t8('Qty'),

#  shipped_qty       => t8('shipped'),

#  not_shipped_qty   => t8('not shipped'),

#  ordnumber         => t8('Order'),

#  customer          => t8('Customer'),

#);

my %sort_columns = (

  my $orderitems = $self->models->get;

    customer          => {      sub => sub { return ''; $_[0]->order->customer->name                                                    },

  $column_defs{$_}->{text} = $sort_columns{$_} for keys %column_defs;

    raw_bottom_info_text  => $self->render('delivery_plan/report_bottom', { output => 0 }, models => $self->models),

  $self->models->sorted->set_report_generator_sort_options(report => $report, sortable_columns => \@sortable);

  $self->models->paginated->disable_pagination if $report->{options}{output_format} =~ /^(pdf|csv)$/i;

sub init_models {

  my ($self) = @_;

  SL::Controller::Helper::GetModels->new(

    controller => $self,

    model  => 'OrderItem', # defaults to controller

    filtered => {

      launder_to => 'filter',

    },

    sorted => {

      _default => {

        by        => 'reqdate',

        dir       => 1,

      },

      %sort_columns,

    },

    query => $delivery_plan_query,

    with_objects => [ 'order', 'order.customer', 'part' ],

  );

}

use parent 'Rose::Object';

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

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

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

use Rose::Object::MakeMethods::Generic (

  scalar => [ qw(controller model query with_objects filtered sorted paginated) ],

  'scalar --get_set_init' => [ qw(handlers) ],

);

#my $registered_handlers = {};

sub init {

  my ($self, %params) = @_;

#  for my $plugin (qw(filtered sorted paginated)) {

#    next unless $params{$plugin};

#    $self->${ \"make_$plugin" }(%{ delete $params{$plugin} || {} });

#  }

#

  # TODO: default model

  $self->model(delete $params{model});

  for my $plugin (qw(filtered sorted paginated)) {

    next unless my $spec = delete $params{$plugin} // {};

    my $plugin_class = "SL::Controller::Helper::GetModels::" . ucfirst $plugin;

    $self->$plugin($plugin_class->new(%$spec, get_models => $self));

  }

  $self->SUPER::init(%params);

}

sub register_handlers {

  my ($self, %additional_handlers) = @_;

#  my $only        = delete($additional_handlers{ONLY}) || [];

#  $only           = [ $only ] if !ref $only;

#  my %hook_params = @{ $only } ? ( only => $only ) : ();

  my $handlers    = $self->handlers;

  my %default_params = $self->_run_handlers('callback', action => $self->controller->action_name);

  return $self->controller->url_for(%default_params, %override_params);

sub get {

  my ($self, %params) = @_;

  push @{ $params{query}        ||= [] }, @{ $self->query || [] };

  push @{ $params{with_objects} ||= [] }, @{ $self->with_objects || [] };

  %params                      = $self->_run_handlers('get_models', %params);

  return $self->manager->get_all(%params);

}

sub get_paginate_args {

  my ($self, %params) = @_;

  push @{ $params{query}        ||= [] }, @{ $self->query || [] };

  push @{ $params{with_objects} ||= [] }, @{ $self->with_objects || [] };

  $self->paginated->get_current_paginate_params(%params);

}

sub manager {

  die "No 'model' to work on" unless $_[0]->model;

  "SL::DB::Manager::" . $_[0]->model;

  foreach my $sub (@{ $self->handlers->{$handler_type} }) {

sub init_handlers {

  {

    callback => [],

    get_models => [],

  }

package SL::Controller::Helper::GetModels::Base;

use strict;

use parent 'Rose::Object';

use Scalar::Util qw(weaken);

use Rose::Object::MakeMethods::Generic (

  scalar => [ qw(get_models) ],

);

sub set_get_models {

  $_[0]->get_models($_[1]);

  weaken($_[1]);

}

sub merge_args {

  my ($self, @args) = @_;

  my $final_args = { };

  for my $field (qw(query with_objects)) {

    $final_args->{$field} = [ map { @{ $_->{$field} || [] } } @args ];

  }

  return %$final_args;

}

1;

package SL::Controller::Helper::GetModels::Filtered;

use strict;

use parent 'SL::Controller::Helper::GetModels::Base';

use Exporter qw(import);

use SL::Controller::Helper::ParseFilter ();

use List::MoreUtils qw(uniq);

use Rose::Object::MakeMethods::Generic (

  scalar => [ qw(disabled filter_args filter_params) ],

  'scalar --get_set_init' => [ qw(form_params launder_to) ],

);

sub init {

  my ($self, %specs)             = @_;

  $self->set_get_models(delete $specs{get_models});

  $self->SUPER::init(%specs);

  $self->get_models->register_handlers(

    callback   => sub { shift; $self->_callback_handler_for_filtered(@_) },

    get_models => sub { shift; $self->_get_models_handler_for_filtered(@_) },

  );

  # $::lxdebug->dump(0, "CONSPEC", \%specs);

}

sub get_current_filter_params {

  my ($self)   = @_;

  return $self->filter_params if $self->filter_params;

  require Carp;

  Carp::confess('It seems a GetModels plugin tries to access filter params before they got calculated. Make sure your make_filtered call comes first.');

}

sub _make_current_filter_params {

  my ($self, %params)   = @_;

#  my $spec              = $self->get_filter_spec;

  my $filter            = $params{filter} // $::form->{ $self->form_params } // {},

  my %filter_args       = $self->_get_filter_args;

  my %parse_filter_args = (

    class        => $self->get_models->manager,

    with_objects => $params{with_objects},

  );

  my $laundered;

  if ($self->launder_to eq '__INPLACE__') {

    # nothing to do

  } elsif ($self->launder_to) {

    $laundered = {};

    $parse_filter_args{launder_to} = $laundered;

  } else {

    $parse_filter_args{no_launder} = 1;

  }

  my %calculated_params = SL::Controller::Helper::ParseFilter::parse_filter($filter, %parse_filter_args);

  %calculated_params = $self->merge_args(\%calculated_params, \%filter_args, \%params);

#  $calculated_params{query} = [

#    @{ $calculated_params{query} || [] },

#    @{ $filter_args{      query} || [] },

#    @{ $params{           query} || [] },

#  ];

#

#  $calculated_params{with_objects} = [

#    uniq

#    @{ $calculated_params{with_objects} || [] },

#    @{ $filter_args{      with_objects} || [] },

#    @{ $params{           with_objects} || [] },

#  ];

  if ($laundered) {

    if ($self->get_models->controller->can($self->launder_to)) {

      $self->get_models->controller->${\ $self->launder_to }($laundered);

    } else {

      $self->get_models->controller->{$self->launder_to} = $laundered;

    }

  }

  # $::lxdebug->dump(0, "get_current_filter_params: ", \%calculated_params);

  $self->filter_params(\%calculated_params);

  return %calculated_params;

}

sub disable_filtering {

  my ($self)               = @_;

  $self->disabled(1);

}

#

# private functions

#

sub _get_filter_args {

  my ($self, $spec) = @_;

  my %filter_args   = ref($self->filter_args) eq 'CODE' ? %{ $self->filter_args->($self) }

                    :     $self->filter_args            ? do { my $sub = $self->filter_args; %{ $self->get_models->controller->$sub() } }

                    :                                       ();

}

sub _callback_handler_for_filtered {

  my ($self, %params) = @_;

  if ($self->is_enabled) {

    my ($flattened) = SL::Controller::Helper::ParseFilter::flatten($::form->{ $self->form_params }, $self->form_params);

    %params         = (%params, @{ $flattened || [] });

  }

  # $::lxdebug->dump(0, "CB handler for filtered; params after flatten:", \%params);

  return %params;

}

sub _get_models_handler_for_filtered {

  my ($self, %params)    = @_;

  # $::lxdebug->dump(0,  "params in get_models_for_filtered", \%params);

  my %filter_params;

  %filter_params = $self->_make_current_filter_params(%params)  if $self->is_enabled;

  # $::lxdebug->dump(0, "GM handler for filtered; params nach modif (is_enabled? " . $self->is_enabled . ")", \%params);

  return (%params, %filter_params);

}

sub is_enabled {

  !$_[0]->disabled;

}

sub init_form_params {

  'filter'

}

sub init_launder_to {

  'filter'

}

1;

__END__

=pod

=encoding utf8

=head1 NAME

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

of filtered lists of database models in a controller

=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) ],

  );

  sub action_list {

    my ($self) = @_;

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

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

  }

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

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

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:

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

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.

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.

=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

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

=back

=head1 BUGS

Nothing here yet.

=head1 AUTHOR

Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>

=cut

package SL::Controller::Helper::GetModels::Paginated;

use strict;

use parent 'SL::Controller::Helper::GetModels::Base';

use List::Util qw(min);

use Rose::Object::MakeMethods::Generic (

  scalar => [ qw(disabled per_page) ],

  'scalar --get_set_init' => [ qw(form_params paginate_args) ],

);

sub init {

  my ($self, %specs)               = @_;

  $self->set_get_models(delete $specs{get_models});

  $self->SUPER::init(%specs);

  $self->per_page($self->get_models->manager->default_objects_per_page) unless $self->per_page;

  $self->get_models->register_handlers(

    callback   => sub { shift; $self->_callback_handler_for_paginated(@_) },

    get_models => sub { shift; $self->_get_models_handler_for_paginated(@_) },

  );

  # $::lxdebug->dump(0, "CONSPEC", \%specs);

}

sub get_current_paginate_params {

  my ($self, %args)   = @_;

  return () unless $self->is_enabled;

  my %paginate_params = $self->final_params(%args);

  # try to use Filtered if available and nothing else is configured, but don't

  # blow up if the controller does not use Filtered

  my %paginate_args     = ref($self->paginate_args) eq 'CODE'       ? %{ $self->paginate_args->($self) }

                        :     $self->paginate_args  eq '__FILTER__'

                           && $self->get_models->filtered ? %{ $self->get_models->filtered->get_current_filter_params }

                        :     $self->paginate_args  ne '__FILTER__' ? do { my $sub = $self->paginate_args; %{ $self->get_models->controller->$sub() } }

                        :                                               ();

  %args = $self->merge_args(\%args, \%paginate_args);

  my $calculated_params = $self->get_models->manager->paginate(%paginate_params, args => \%args);

  # $::lxdebug->dump(0, "get_current_paginate_params: ", $calculated_params);

  return %{ $calculated_params };

}

sub disable_pagination {

  my ($self)               = @_;

  $self->disabled(1);

}

sub final_params {

  my ($self, %params)      = @_;

  my $from_form = {

    page            => $::form->{ $self->form_params->[0] } || 1,

    per_page        => $::form->{ $self->form_params->[1] } * 1,

  };

#  my $priv              = _priv($self);

  $params{page}         = $from_form->{page}     unless defined $params{page};

  $params{per_page}     = $from_form->{per_page} unless defined $params{per_page};

  $params{page}         = ($params{page} * 1) || 1;

  $params{per_page}     = ($params{per_page} * 1) || $self->per_page;

  %params;

}

#

# private functions

#

sub init_form_params {

  [ qw(page per_page) ]

}

sub init_paginate_args {

  '__FILTER__'

}

sub _callback_handler_for_paginated {

  my ($self, %params) = @_;

  my %form_params = $self->final_params;

#  my $priv            = _priv($self);

  if ($self->is_enabled && $form_params{page}) {

    $params{ $self->form_params->[0] } = $form_params{page};

    $params{ $self->form_params->[1] } = $form_params{per_page} if $form_params{per_page};

  }

  # $::lxdebug->dump(0, "CB handler for paginated; params nach modif:", \%params);

  return %params;

}

sub _get_models_handler_for_paginated {

  my ($self, %params)    = @_;

  $self->get_models->manager->paginate($self->final_params, args => \%params) if $self->is_enabled;

  # $::lxdebug->dump(0, "GM handler for paginated; params nach modif (is_enabled? " . _is_enabled($self) . ")", \%params);

  return %params;

}

sub is_enabled {

  my ($self) = @_;

  return !$self->disabled;

}

1;

__END__

=pod

=encoding utf8

=head1 NAME

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

of paginating lists of database models in a controller

=head1 SYNOPSIS

In a controller:

  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);

  }

In said template:

  [% USE L %]

  <table>

   <thead>

    <tr>

     ...

    </tr>

   </thead>

   <tbody>

    [% FOREACH entry = ENTRIES %]

     <tr>

      ...

     </tr>

    [% END %]

   </tbody>

  </table>

  [% L.paginate_controls %]

=head1 OVERVIEW

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.

For this to work the controller has to provide the information which

indexes are eligible for paginateing etc. by a call to

L<make_paginated> at compile time.

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

more information on it.

A template can use the method C<paginate_controls> from the layout

helper module C<L> which renders the links for navigation between the

pages.

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

helper.

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

=over 4

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

Defaults to the underlying database model's default number of models

per page.

=item * C<FORM_PARAMS>

Optional. An array reference with exactly two strings that name the

indexes in C<$::form> in which the current page's number (the first

element in the array) and the number of models per page (the second

element in the array) are stored.

Defaults to the values C<page> and C<per_page> if missing.

=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

=back

=head1 INSTANCE FUNCTIONS

These functions are called on a controller instance.

=over 4

=item C<get_paginate_spec>

Returns a hash containing the currently active paginate

parameters. The following keys are returned:

=over 4

=item * C<page>

The currently active page number (numbering starts at 1).

=item * C<per_page>

Number of models per page (at least 1).

=item * C<num_pages>

Number of pages to display (at least 1).

=item * C<common_pages>

An array reference with one hash reference for each possible

page. Each hash ref contains the keys C<active> (C<1> if that page is

the currently active page), C<page> (the page number this hash

reference describes) and C<visible> (whether or not it should be

displayed).

=back

=item C<get_current_paginate_params>

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

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

applying default parameters etc).

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

=back

=head1 BUGS

Nothing here yet.

=head1 AUTHOR

Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>

=cut

package SL::Controller::Helper::GetModels::Sorted;

use strict;

use parent 'SL::Controller::Helper::GetModels::Base';

use Carp;

use List::MoreUtils qw(uniq);

use Rose::Object::MakeMethods::Generic (

  scalar => [ qw(by dir specs) ],

  'scalar --get_set_init' => [ qw(form_params) ],

);

sub init {

  my ($self, %specs) = @_;

  $self->set_get_models(delete $specs{get_models});

  my %model_sort_spec   = $self->get_models->manager->_sort_spec;

  if (my $default = delete $specs{_default}) {

    $self->by ($default->{by});

    $self->dir($default->{dir});

  } else {

    $self->by ($model_sort_spec{default}[0]);

    $self->dir($model_sort_spec{default}[1]);

  }

  while (my ($column, $spec) = each %specs) {

    next if $column =~ m/^[A-Z_]+$/;

    $spec = $specs{$column} = { title => $spec } if (ref($spec) || '') ne 'HASH';

    $spec->{model}        ||= $self->get_models->model;

    $spec->{model_column} ||= $column;

  }

  $self->specs(\%specs);

  $self->get_models->register_handlers(

    callback   => sub { shift; $self->_callback_handler_for_sorted(@_) },

    get_models => sub { shift; $self->_get_models_handler_for_sorted(@_) },

  );

#   $::lxdebug->dump(0, "CONSPEC", \%specs);

}

sub get_current_sort_params {

  my ($self, %params) = @_;

  my %sort_params;

  my ($by, $dir) = @{ $self->form_params };

  if ($::form->{ $by }) {

    %sort_params = (

      sort_by  => $::form->{$by},

      sort_dir => defined($::form->{$dir}) ? $::form->{$dir} * 1 : undef,

    );

  } elsif (!$self->by) {

    %sort_params = %params;

  } else {

    %sort_params = (

      sort_by  => $self->by,

      sort_dir => $self->dir,

    );

  }

  return %sort_params;

}

sub set_report_generator_sort_options {

  my ($self, %params) = @_;

  $params{$_} or croak("Missing parameter '$_'") for qw(report sortable_columns);

  my %current_sort_params = $self->get_current_sort_params;

  foreach my $col (@{ $params{sortable_columns} }) {

    $params{report}->{columns}->{$col}->{link} = $self->get_models->get_callback(

      sort_by  => $col,

      sort_dir => ($current_sort_params{sort_by} eq $col ? 1 - $current_sort_params{sort_dir} : $current_sort_params{sort_dir}),

    );

  }

  $params{report}->set_sort_indicator($current_sort_params{sort_by}, 1 - $current_sort_params{sort_dir});

  if ($params{report}->{export}) {

    $params{report}->{export}->{variable_list} = [ uniq(

      @{ $params{report}->{export}->{variable_list} },

      @{ $self->form_params }

    )];

  }

}

#

# private functions

#

sub _callback_handler_for_sorted {

  my ($self, %params) = @_;

  my %spec = $self->get_current_sort_params;

  if ($spec{sort_by}) {

    $params{ $self->form_params->[0] } = $spec{sort_by};

    $params{ $self->form_params->[1] } = $spec{sort_dir};

  }

  # $::lxdebug->dump(0, "CB handler for sorted; params nach modif:", \%params);

  return %params;

}

sub _get_models_handler_for_sorted {

  my ($self, %params) = @_;

  my %sort_params     = $self->get_current_sort_params;

  my $sort_spec       = $self->specs->{ $sort_params{sort_by} };

  $params{sort_by}    = "SL::DB::Manager::$sort_spec->{model}"->make_sort_string(sort_by => $sort_spec->{model_column}, sort_dir => $sort_params{sort_dir});

  # $::lxdebug->dump(0, "GM handler for sorted; params nach modif:", \%params);

  return %params;

}

sub init_form_params {

  [ qw(sort_by sort_dir) ]

}

1;

__END__

=pod

=encoding utf8

=head1 NAME

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

of sorting lists of database models in a controller

=head1 SYNOPSIS

In a controller:

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

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

  __PACKAGE__->make_sorted(

    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:

  [% USE L %]

  <table>

   <tr>

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

    <th>[% L.sortable_table_header('run_at') %]</th>

    <th>[% L.sortable_table_header('error') %]</th>

   </tr>

   [% FOREACH entry = ENTRIES %]

    <tr>

     <td>[% HTML.escape(entry.package_name) %]</td>

     <td>[% HTML.escape(entry.run_at) %]</td>

     <td>[% HTML.escape(entry.error) %]</td>

    </tr>

   [% END %]

  </table>

=head1 OVERVIEW

This specialized helper module enables controllers to display a

sortable list of database models with as few lines as possible.

For this to work the controller has to provide the information which

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

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

=over 4

=item C<make_sorted %sort_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.

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>

Optional. An array reference with exactly two strings that name the

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

the array) and sort direction (the second element in the array) are

stored.