SL/Presenter/DatePeriod.pm

   1 package SL::Presenter::DatePeriod;
   2
   3 use strict;
   4
   5 use Exporter qw(import);
   6 our @EXPORT_OK = qw(
   7   date_period_picker
   8   get_dialog_defaults_from_report_generator
   9   populate_hidden_variables
  10 );
  11
  12 use SL::Presenter::Tag qw(name_to_id);
  13
  14 sub date_period_picker {
  15   my ($name, $value_from, $value_to, %params) = @_;
  16
  17   my $id = name_to_id($name);
  18   my @classes = $params{class} ? ($params{class}) : ();
  19   push @classes, 'date_period_picker';
  20
  21   my $dialog_defaults = {
  22     year => $params{dialog_defaults}->{year} // DateTime->today->year,
  23     type => $params{dialog_defaults}->{type} // 'yearly',
  24     quarter => $params{dialog_defaults}->{quarter} // 'A',
  25     month => $params{dialog_defaults}->{month} // '1',
  26   };
  27
  28   my $html = SL::Presenter->get->render(
  29     'presenter/date_period/date_period_picker',
  30     id => $id,
  31     classes => \@classes,
  32     defaults => {
  33       report_period_from_date => $value_from || '',
  34       report_period_to_date => $value_to || '',
  35       dialog => $dialog_defaults
  36     },
  37     years_list => get_years(),
  38     months_list => get_months(),
  39   );
  40   $::request->layout->add_javascripts('kivi.Presenter.DatePeriodPicker.js');
  41
  42   return $html;
  43 }
  44
  45 ### convenience functions
  46
  47 sub get_dialog_defaults_from_report_generator {
  48   my ($name) = @_;
  49
  50   my $id = name_to_id($name);
  51
  52   my %fallback_dateperiod_dialog = (
  53     year => DateTime->today->year,
  54     type => 'yearly',
  55     quarter => 'A',
  56     month => '1',
  57   );
  58   my %defaults_dialog;
  59   for (keys %fallback_dateperiod_dialog) {
  60     $defaults_dialog{$_} = $::form->{$id . '_selected_preset_' . $_} //
  61                             $::form->{'report_generator_hidden_' . $id . '_selected_preset_' . $_} //
  62                             $fallback_dateperiod_dialog{$_};
  63   }
  64   return \%defaults_dialog;
  65 }
  66
  67 sub populate_hidden_variables {
  68   my ($name, $hidden_variables_ref) = @_;
  69
  70   my $id = name_to_id($name);
  71
  72   my @vars = qw(
  73     _from_date
  74     _to_date
  75     _selected_preset_year
  76     _selected_preset_type
  77     _selected_preset_quarter
  78     _selected_preset_month
  79   );
  80
  81   push @{ $hidden_variables_ref }, map { $id . $_ } @vars;
  82 }
  83
  84 ### helper
  85
  86 sub get_months {
  87   my $dt = DateTime->now;
  88   my $months = $dt->{locale}->{locale_data}->{month_format_wide};
  89   my $i = 0;
  90   [ map { $i++; [ $i, $::locale->text($_) ] } @{ $months } ];
  91 }
  92
  93 sub get_years {
  94   my $current = DateTime->today->year;
  95   [ map { [ $current - $_, $current - $_, ] } (0..39) ];
  96 }
  97
  98 sub picker { goto &date_period_picker }
  99
 100 1;
 101
 102 __END__
 103
 104 =encoding utf-8
 105
 106 =head1 NAME
 107
 108 SL::Presenter::DatePeriod - Date period stuff
 109
 110 =head1 SYNOPSIS
 111
 112   # use in perl code
 113   use SL::Presenter::DatePeriod qw(date_period_picker);
 114   my $html   = date_period_picker('my-picker-id', '', '');
 115   my $html   = date_period_picker('my-other-picker-id', $from_date, $to_date);
 116
 117   # use in template
 118   [% P.date_period.picker('my-picker-id', '', '') %]
 119   [% P.date_period.picker('my-other-picker-id',
 120                             defaults.from_date,
 121                             defaults.to_date,
 122                             dialog_defaults => defaults.dialog) %]
 123
 124 see also L<SL::Presenter>
 125
 126 =head1 DATE PERIOD PICKER UI DESCRIPTION
 127
 128 Two date input fields are shown: 'From' and 'To', to select a date period.
 129
 130 Additionally a button is shown: 'Select from preset'.
 131
 132 When clicked it shows a dialog that allows the selection of a date period
 133 from sensible presets.
 134
 135 =over 2
 136
 137 =item Dialog:
 138
 139 The dialog shows a select 'Year', containing the current year plus years up
 140 to forty years back.
 141
 142 A period is selected with a radio button, that is either 'yearly' (default),
 143 'quarterly' or 'monthly'.
 144
 145 For quarterly and monthly there is a select shown containing the respective
 146 values.
 147
 148 =back
 149
 150 =head1 FUNCTIONS
 151
 152 =over 2
 153
 154 =item C<date_period_picker $name, $value_from, $value_to, %params>
 155
 156 Renders a date period picker with preset dialog.
 157
 158 C<$name> should be a unique name. It is converted to an id for the main
 159 element. This id is also used as a prefix for all sub-elements that need an id.
 160
 161 B<Important:> The selected dates are available from the form elements
 162
 163 C<id _ '_from_date'> and C<id _ '_to_date'>.
 164
 165 In above example this would be C<'my-picker-id_from_date'> and
 166 C<'my-picker-id_to_date'>.
 167
 168 C<$value_from> and C<$value_to> are used as preset values for the respective
 169 date fields. This may be useful to keep entered value between page switches.
 170
 171 C<$params> Classes in C<class> are forwarded to the main element.
 172
 173 If you want to keep the selection over multiple requests this has to be handled
 174 in the controller.
 175
 176 C<$params> can therefor contain a hash called C<dialog_defaults> with the
 177 key/values:
 178
 179   year => DateTime->today->year,  # numeric year
 180   type => 'yearly',               # the radio button selection:
 181                                   # 'yearly', 'monthly', 'quarterly'
 182   quarter => 'A',                 # the quarter as a letter code:
 183                                   # 'A', 'B', 'C', 'D' A being 1st quarter etc.
 184   month => '1',                   # numeric month
 185
 186 The values will be used to pre-select the dialog fields.
 187
 188 These values are also set into some hidden fields with the id in the format
 189 e.g.: C<id _ '_selected_preset_year'>.
 190
 191 Convenience functions to handle report generator hidden variables are provided.
 192 E.g.:
 193
 194   use SL::Presenter::DatePeriod qw(get_dialog_defaults_from_report_generator
 195                                     populate_hidden_variables);
 196
 197   # use values from form, then report generator form, then fallback
 198   my %fallback = (
 199     dateperiod_from_date => '',
 200     dateperiod_to_date => '',
 201     # other fields e.g.:
 202     # chart_id      => '',
 203   );
 204   my %defaults;
 205   for (keys %fallback) {
 206     $defaults{$_} = $::form->{$_} // $::form->{'report_generator_hidden_' . $_} // $fallback{$_};
 207   }
 208
 209   # set dialog defaults
 210   $defaults{dialog} = get_dialog_defaults_from_report_generator('dateperiod');
 211
 212   # set hidden fields for the report generator
 213   my @hidden_variables = qw(chart_id);    # e.g.
 214   populate_hidden_variables('dateperiod', \@hidden_variables);
 215
 216 =item C<get_dialog_defaults_from_report_generator $name>
 217
 218 Convenience function to get the dialog defaults from hidden report generator
 219 fields. (Use in controller.)
 220
 221 First uses form fields: C<$id . '_selected_preset_' ...>.
 222 Then report generator fields: C<'report_generator_hidden_' . $id . '_selected_preset_' ...>
 223
 224 C<$name> name of the date picker.
 225
 226 =item C<populate_hidden_variables $name $hidden_variables_ref>
 227
 228 Convenience function Add hidden variables to report a generator.
 229 (Use in controller.)
 230
 231 C<$name> name of the date picker.
 232
 233 C<$hidden_variables_ref> reference to the hidden variable array.
 234
 235 =back
 236
 237 =head1 USE / MOTIVATION / GOAL
 238
 239 Use date_period_picker when you want to select a date period with preset
 240 dialog.
 241
 242 Planned use: ListTransactions report settings view (new, replacement for
 243 ca/list).
 244
 245 Possible uses in report settings views for:
 246
 247   - rp/erfolgsrechnung (swiss)
 248   - rp/trial_balance
 249   - Inventory/stock_usage
 250
 251 And possibly more.
 252
 253 Current implementations for report periods repeat a lot of template and
 254 perl code in different places. Hopefully this can be reduced.
 255
 256 While this UI may require slightly more clicks than previous / current
 257 implementations, the interface is much more concise. It is easier on the eyes
 258 and fits better into the new design 4.0.
 259
 260 =head1 LIMITATIONS
 261
 262 If multiple date_period_picker elements were to be used on the same page the
 263 handling of hidden variables becomes ugly.
 264
 265   my @hidden_variables = qw(
 266     dateperiod_from_date
 267     dateperiod_to_date
 268     dateperiod_selected_preset_year
 269     dateperiod_selected_preset_type
 270     # ... etc.
 271   );
 272
 273 Convenience functions are provided to help handle this. Currently i don't see
 274 another way of handling this.
 275
 276 =head1 BUGS
 277
 278 None atm :)
 279
 280 =head1 AUTHOR
 281
 282 Cem Aydin E<lt>cem.aydin@revamp-it.chE<gt>
 283
 284 =cut