Doku cleanup

diff --git a/SL/Controller/Helper/GetModels/Filtered.pm b/SL/Controller/Helper/GetModels/Filtered.pm
index 88a29886074c55f35a8ae99c82920987f666d25d..6d2be88e94b7dd2ef65d519f85175afb72bd743e 100644 (file)
--- a/SL/Controller/Helper/GetModels/Filtered.pm
+++ b/SL/Controller/Helper/GetModels/Filtered.pm
@@ -140,7 +140,6 @@ In a controller:
     filtered => 0,
   );
 
     filtered => 0,
   );
 

-

 =head1 OVERVIEW
 
 This C<GetModels> plugin enables use of the
 =head1 OVERVIEW
 
 This C<GetModels> plugin enables use of the

diff --git a/SL/Controller/Helper/GetModels/Paginated.pm b/SL/Controller/Helper/GetModels/Paginated.pm
index 871f4b5c173d587bcdfe4c0ddfac05f37ebcfc55..ad5e10c147c6757016994c0f321b09e8504d118e 100644 (file)
--- a/SL/Controller/Helper/GetModels/Paginated.pm
+++ b/SL/Controller/Helper/GetModels/Paginated.pm
@@ -122,59 +122,30 @@ of paginating lists of database models in a controller
 
 In a controller:
 
 
 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) ],
+  SL::Controller::Helper::GetModels->new(
+    ..
+    paginated => {
+      form_params => [ qw(page per_page) ],
+      per_page    => 20,
+    }

   );
 
   );
 

-  sub action_list {
-    my ($self) = @_;
-
-    my $paginated_models = $self->get_models;
-    $self->render('controller/list', ENTRIES => $paginated_models);
-  }
-

 In said template:
 
 In said template:
 

-  [% USE L %]
-
-  <table>
-   <thead>
-    <tr>
-     ...
-    </tr>
-   </thead>
-
-   <tbody>
-    [% FOREACH entry = ENTRIES %]
-     <tr>
-      ...
-     </tr>
-    [% END %]
-   </tbody>
-  </table>
-

   [% L.paginate_controls %]
 
 =head1 OVERVIEW
 
   [% 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.
+This C<GetModels> plugin enables controllers to display a
+paginatable list of database models with as few lines as possible.

 
 For this to work the controller has to provide the information which
 
 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.
+indexes are eligible for paginateing etc. during C<GetModels> creation.

 
 The underlying functionality that enables the use of more than just
 the paginate helper is provided by the controller helper
 
 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.
+C<GetModels>. See the documentation for L<SL::Controller::Helper::GetModels>
+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
 
 A template can use the method C<paginate_controls> from the layout
 helper module C<L> which renders the links for navigation between the


@@ -183,53 +154,18 @@ pages.
 This module requires that the Rose model managers use their C<Paginated>
 helper.
 
 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
+=head1 OPTIONS

 
 =over 4
 
 
 =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>
+=item * C<per_page>

 
 

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

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

-=item * C<FORM_PARAMS>
+=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
 
 Optional. An array reference with exactly two strings that name the
 indexes in C<$::form> in which the current page's number (the first


@@ -238,19 +174,11 @@ element in the array) are stored.
 
 Defaults to the values C<page> and C<per_page> if missing.
 
 
 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
 
 =back
 
 =head1 INSTANCE FUNCTIONS
 

-These functions are called on a controller instance.
+These functions are called on a C<GetModels> instance and delegated here.

 
 =over 4
 
 
 =over 4
 


@@ -285,24 +213,26 @@ displayed).
 
 =item C<get_current_paginate_params>
 
 
 =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,
+Returns a hash reference to the paginate spec structure given in the
+configuration after normalization (hash reference construction,

 applying default parameters etc).
 
 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
 
 =back
 
 =head1 BUGS
 

-Nothing here yet.
+C<common_pages> generates an array with an entry for every page, which gets
+slow if there are a lot of entries. Current observation holds that up to about
+1000 pages there is no noticable slowdown, but at about 10000 it gets
+noticable. At 100k-500k pages it's takes way too long and should be remodelled.
+
+This case currently only applies for databases with very large amounts of parts
+that get paginated, but BackgroundJobHistory can also accumulate.

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

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

 =cut
 =cut

diff --git a/SL/Controller/Helper/GetModels/Sorted.pm b/SL/Controller/Helper/GetModels/Sorted.pm
index 14e733d452c397a96c8098f8e8d98c867e73c106..c20dc3f078bb1b16c687b86a09714a97359a6c1a 100644 (file)
--- a/SL/Controller/Helper/GetModels/Sorted.pm
+++ b/SL/Controller/Helper/GetModels/Sorted.pm
@@ -143,34 +143,26 @@ of sorting lists of database models in a controller
 
 In a controller:
 
 
 In a controller:
 

-  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'),
+  SL::Controller::Helper::GetModels->new(
+    ...
+    sorted => {
+      _default => {
+        by  => 'run_at',
+        dir => 1,
+      },
+      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:
+In template:

 
   [% USE L %]
 
   <table>
    <tr>
 
   [% USE L %]
 
   <table>
    <tr>

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

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


@@ -186,95 +178,44 @@ In said template:
 
 =head1 OVERVIEW
 
 
 =head1 OVERVIEW
 

-This specialized helper module enables controllers to display a
+This C<GetModels> plugin 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
 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  #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>.
+indexes are eligible for sorting etc. through it's configuration of
+C<GetModels>.

 
 

-This module requires that the Rose model managers use their C<Sorted>
-helper.
+A template can then use the method C<sortable_table_header> from the layout
+helper module C<L>.

 
 

-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.
+This module requires that the Rose model managers use their
+C<SL::DB::Helper::Sorted> helper.

 
 

-=head1 PACKAGE FUNCTIONS
+=head1 OPTIONS

 
 =over 4
 
 
 =over 4
 

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

 
 

-=item * C<MODEL>
+Optional. If it exists, it is expected to contain the keys C<by> and C<dir> and
+will be used to set the default sorting if nothing is found in C<source>.

 
 

-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>).
+Defaults to the underlying database model's default.

 
 

-=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>
+=item * C<form_params>

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

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

 the array) and sort direction (the second element in the array) are
 stored.
 
 Defaults to the values C<sort_by> and C<sort_dir> if missing.
 
 the array) and sort direction (the second element in the array) are
 stored.
 
 Defaults to the values C<sort_by> and C<sort_dir> if missing.
 

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

 =back
 
 =back
 

-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
+All other keys 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

 used as the value for the C<title> key.
 
 These possible elements are:
 used as the value for the C<title> key.
 
 These possible elements are:


@@ -311,7 +252,7 @@ reference is the value.
 
 =head1 INSTANCE FUNCTIONS
 
 
 =head1 INSTANCE FUNCTIONS
 

-These functions are called on a controller instance.
+These functions are called on a C<GetModels> instance and delegating to this plugin.

 
 =over 4
 
 
 =over 4
 


@@ -320,15 +261,15 @@ These functions are called on a controller instance.
 Returns a hash containing the currently active sort parameters.
 
 The key C<by> contains the active sort index referring to the
 Returns a hash containing the currently active sort parameters.
 
 The key C<by> contains the active sort index referring to the

-C<%sort_spec> given to L<make_sorted>.
+C<%sort_spec> given by the configuration.

 
 The key C<dir> is either C<1> or C<0>.
 
 =item C<get_current_sort_params>
 
 
 The key C<dir> is either C<1> or C<0>.
 
 =item C<get_current_sort_params>
 

-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).
+Returns a hash reference to the sort spec structure given in the configuration
+after normalization (hash reference construction, applying default parameters
+etc).

 
 =item C<set_report_generator_sort_options %params>
 
 
 =item C<set_report_generator_sort_options %params>
 


@@ -342,7 +283,7 @@ L<SL::ReportGenerator>:
 =item 2. it sets the the links for those column headers that are
 sortable and
 
 =item 2. it sets the the links for those column headers that are
 sortable and
 

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

 the report generator's export options.
 
 =back
 the report generator's export options.
 
 =back


@@ -365,4 +306,6 @@ Nothing here yet.
 
 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 
 
 Moritz Bunkus E<lt>m.bunkus@linet-services.deE<gt>
 

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

 =cut
 =cut