SL/Presenter/Chart.pm

   1 package SL::Presenter::Chart;
   2
   3 use strict;
   4
   5 use SL::DB::Chart;
   6
   7 use Exporter qw(import);
   8 use Data::Dumper;
   9 our @EXPORT = qw(chart_picker chart);
  10
  11 use Carp;
  12
  13 sub chart {
  14   my ($self, $chart, %params) = @_;
  15
  16   $params{display} ||= 'inline';
  17
  18   croak "Unknown display type '$params{display}'" unless $params{display} =~ m/^(?:inline|table-cell)$/;
  19
  20   my $text = join '', (
  21     $params{no_link} ? '' : '<a href="am.pl?action=edit_account&id=' . $self->escape($chart->id) . '">',
  22     $self->escape($chart->accno),
  23     $params{no_link} ? '' : '</a>',
  24   );
  25   return $self->escaped_text($text);
  26 }
  27
  28 sub chart_picker {
  29   my ($self, $name, $value, %params) = @_;
  30
  31   $value = SL::DB::Manager::Chart->find_by(id => $value) if $value && !ref $value;
  32   my $id = delete($params{id}) || $self->name_to_id($name);
  33   my $fat_set_item = delete $params{fat_set_item};
  34
  35   my @classes = $params{class} ? ($params{class}) : ();
  36   push @classes, 'chart_autocomplete';
  37   push @classes, 'chartpicker_fat_set_item' if $fat_set_item;
  38
  39   my $ret =
  40     $self->input_tag($name, (ref $value && $value->can('id') ? $value->id : ''), class => "@classes", type => 'hidden', id => $id) .
  41     join('', map { $params{$_} ? $self->input_tag("", delete $params{$_}, id => "${id}_${_}", type => 'hidden') : '' } qw(type category choose booked)) .
  42     $self->input_tag("", (ref $value && $value->can('displayable_name')) ? $value->displayable_name : '', id => "${id}_name", %params);
  43
  44   $::request->layout->add_javascripts('autocomplete_chart.js');
  45   $::request->presenter->need_reinit_widgets($id);
  46
  47   $self->html_tag('span', $ret, class => 'chart_picker');
  48 }
  49
  50 1;
  51
  52 __END__
  53
  54 =encoding utf-8
  55
  56 =head1 NAME
  57
  58 SL::Presenter::Chart - Chart related presenter stuff
  59
  60 =head1 SYNOPSIS
  61
  62   # Create an html link for editing/opening a chart
  63   my $object = SL::DB::Manager::Chart->get_first;
  64   my $html   = SL::Presenter->get->chart($object, display => 'inline');
  65
  66 see also L<SL::Presenter>
  67
  68 =head1 DESCRIPTION
  69
  70 see L<SL::Presenter>
  71
  72 =head1 FUNCTIONS
  73
  74 =over 2
  75
  76 =item C<chart, $object, %params>
  77
  78 Returns a rendered version (actually an instance of
  79 L<SL::Presenter::EscapedText>) of the chart object C<$object>
  80
  81 C<%params> can include:
  82
  83 =over 4
  84
  85 =item * display
  86
  87 Either C<inline> (the default) or C<table-cell>. At the moment both
  88 representations are identical and produce the chart's name linked
  89 to the corresponding 'edit' action.
  90
  91 =back
  92
  93 =back
  94
  95 =over 2
  96
  97 =item C<chart_picker $name, $value, %params>
  98
  99 All-in-one picker widget for charts. The code was originally copied and adapted
 100 from the part picker. The name will be both id and name of the resulting hidden
 101 C<id> input field (but the ID can be overwritten with C<$params{id}>).
 102
 103 An additional dummy input will be generated which is used to find
 104 chart. For a detailed description of its behaviour, see section
 105 C<CHART PICKER SPECIFICATION>.
 106
 107 For some examples of usage see the test page at controller.pl?action=Chart/test_page
 108
 109 C<$value> can be a chart id or a C<Rose::DB:Object> instance.
 110
 111 C<%params> can include:
 112
 113 =over 4
 114
 115 =item * category
 116
 117 If C<%params> contains C<category> only charts of this category will be
 118 available for selection (in the autocompletion and in the popup).
 119
 120 You may comma separate multiple categories, e.g C<A,Q,L>.
 121
 122 In SL::DB::Manager::Chart there is also a filter called C<selected_category>,
 123 which filters the possible charts according to the category checkboxes the user
 124 selects in the popup window. This filter may further restrict the results of
 125 the filter category, but the user is not able to "break out of" the limits
 126 defined by C<category>. In fact if the categories are restricted by C<category>
 127 the popup template should only show checkboxes for those categories.
 128
 129 =item * type
 130
 131 If C<%params> contains C<type> only charts of this type will be used for
 132 autocompletion, i.e. the selection is filtered. You may comma separate multiple
 133 types.
 134
 135 Type is usually a filter for link: C<AR,AR_paid>
 136
 137 Type can also be a specially defined type: C<guv>, C<balance>, C<bank>
 138
 139 See the type filter in SL::DB::Manager::Chart.
 140
 141 =item * choose
 142
 143 If C<%params> is passed with choose=1 the input of the filter field in the
 144 popup window is cleared. This is useful if a chart was already selected and we
 145 want to choose a new chart and immediately see all options.
 146
 147 =item * fat_set_item
 148
 149 If C<%params> is passed with fat_set_item=1 the contents of the selected chart
 150 object (the elements of the database chart table) are passed back via JSON into
 151 the item object. There is an example on the test page.
 152
 153 Without fat_set_item only the variables id and name (displayable name) are
 154 available.
 155
 156 =back
 157
 158 C<chart_picker> will register its javascript for inclusion in the next header
 159 rendering. If you write a standard controller that only calls C<render> once, it
 160 will just work.  In case the header is generated in a different render call
 161 (multiple blocks, ajax, old C<bin/mozilla> style controllers) you need to
 162 include C<js/autocomplete_part.js> yourself.
 163
 164 =back
 165
 166 =head1 POPUP LAYER
 167
 168 For users that don't regularly do bookkeeping and haven't memorised all the
 169 account numbers and names there are some filter options inside the popup window
 170 to quickly narrow down the possible matches. You can filter by
 171
 172 =over 4
 173
 174 =item * chart accno or description, inside the input field
 175
 176 =item * accounts that have already been booked
 177
 178 =item * by category (AIELQC)
 179
 180 By selecting category checkboxes the list of available charts can be
 181 restricted. If all checkboxes are unchecked all possible charts are shown.
 182
 183 =back
 184
 185 There are two views in the list of accounts. By default all possible accounts are shown as a long list.
 186
 187 But you can also show more information, in this case the resulting list is automatically paginated:
 188
 189 =over 4
 190
 191 =item * the balance of the account (as determined by SL::DB::Chart get_balance, which checks for user rights)
 192
 193 =item * the category
 194
 195 =item * the invoice date of the last transaction (may lie in the future)
 196
 197 =back
 198
 199 The partpicker also has two views, but whereas the compact block view of the
 200 partpicker allows part boxes to be aligned in two columns, the chartpicker
 201 block view still only shows one chart per row, because there is more
 202 information and the account names can be quite long. This behaviour is
 203 determined by css, however, and could be changed (div.cpc_block).  The downside
 204 of this is that you have to scroll the window to reach the pagination controls.
 205
 206 The default view of the display logic is to use block view, so we don't have to
 207 pass any parameters in the pagination GET. However, the default view for the
 208 user is the list view, so the popup window is opened with the "Hide additional
 209 information" select box already ticked.
 210
 211 =head1 CHART PICKER SPECIFICATION
 212
 213 The following list of design goals were applied:
 214
 215 =over 4
 216
 217 =item *
 218
 219 Charts should not be perceived by the user as distinct inputs of chart number and
 220 description but as a single object
 221
 222 =item *
 223
 224 Easy to use without documentation for novice users
 225
 226 =item *
 227
 228 Fast to use with keyboard for experienced users
 229
 230 =item *
 231
 232 Possible to use without any keyboard interaction for mouse (or touchscreen)
 233 users
 234
 235 =item *
 236
 237 Must not leave the current page in event of ambiguity (cf. current select_item
 238 mechanism)
 239
 240 =item *
 241
 242 Should not require a feedback/check loop in the common case
 243
 244 =item *
 245
 246 Should not be constrained to exact matches
 247
 248 =back
 249
 250 The implementation consists of the following parts which will be referenced later:
 251
 252 =over 4
 253
 254 =item 1
 255
 256 A hidden input (id input), used to hold the id of the selected part. The only
 257 input that gets submitted
 258
 259 =item 2
 260
 261 An input (dummy input) containing a description of the currently selected chart,
 262 also used by the user to search for charts
 263
 264 =item 3
 265
 266 A jquery.autocomplete mechanism attached to the dummy field
 267
 268 =item 4
 269
 270 A popup layer for both feedback and input of additional data in case of
 271 ambiguity.
 272
 273 =item 5
 274
 275 An internal status of the chart picker, indicating whether id input and dummy
 276 input are consistent. After leaving the dummy input the chart picker must
 277 place itself in a consistent status.
 278
 279 =item 6
 280
 281 A clickable icon (popup trigger) attached to the dummy input, which triggers the popup layer.
 282
 283 =back
 284
 285 =head1 BUGS
 286
 287 None atm :)
 288
 289 =head1 AUTHOR
 290
 291 Sven Schöling E<lt>s.schoeling@linet-services.deE<gt>
 292
 293 G. Richardson E<lt>information@kivitendo-premium.deE<gt>
 294
 295 =cut