ReportGenerator: Unterstützung für das Verbinden von Tabellenzellen mit dem "colspan...
[kivitendo-erp.git] / SL / ReportGenerator.pm
1 package SL::ReportGenerator;
2
3 use IO::Wrap;
4 use List::Util qw(max);
5 use Text::CSV_XS;
6 use Text::Iconv;
7
8 use SL::Form;
9
10 # Cause locales.pl to parse these files:
11 # parse_html_template('report_generator/html_report')
12
13 sub new {
14   my $type = shift;
15
16   my $self = { };
17
18   $self->{myconfig} = shift;
19   $self->{form}     = shift;
20
21   $self->{data}     = [];
22   $self->{options}  = {
23     'std_column_visibility' => 0,
24     'output_format'         => 'HTML',
25     'allow_pdf_export'      => 1,
26     'allow_csv_export'      => 1,
27     'html_template'         => 'report_generator/html_report',
28     'pdf_export'            => {
29       'paper_size'          => 'a4',
30       'orientation'         => 'landscape',
31       'font_name'           => 'Verdana',
32       'font_size'           => '7',
33       'margin_top'          => 1.5,
34       'margin_left'         => 1.5,
35       'margin_bottom'       => 1.5,
36       'margin_right'        => 1.5,
37       'number'              => 1,
38       'print'               => 0,
39       'printer_id'          => 0,
40       'copies'              => 1,
41     },
42     'csv_export'            => {
43       'quote_char'          => '"',
44       'sep_char'            => ';',
45       'escape_char'         => '"',
46       'eol_style'           => 'Unix',
47       'headers'             => 1,
48     },
49   };
50   $self->{export}   = {
51     'nextsub'       => '',
52     'variable_list' => [],
53   };
54
55   $self->{data_present} = 0;
56
57   bless $self, $type;
58
59   $self->set_options(@_) if (@_);
60
61   return $self;
62 }
63
64 sub set_columns {
65   my $self    = shift;
66   my %columns = @_;
67
68   $self->{columns} = \%columns;
69
70   foreach my $column (values %{ $self->{columns} }) {
71     $column->{visible} = $self->{options}->{std_column_visibility} unless defined $column->{visible};
72   }
73
74   $self->set_column_order(sort keys %{ $self->{columns} });
75 }
76
77 sub set_column_order {
78   my $self    = shift;
79   my %seen;
80   $self->{column_order} = [ grep { !$seen{$_}++ } @_, sort keys %{ $self->{columns} } ];
81 }
82
83 sub set_sort_indicator {
84   my $self = shift;
85
86   $self->{options}->{sort_indicator_column}    = shift;
87   $self->{options}->{sort_indicator_direction} = shift;
88 }
89
90 sub add_data {
91   my $self = shift;
92
93   my $last_row_set;
94
95   while (my $arg = shift) {
96     my $row_set;
97
98     if ('ARRAY' eq ref $arg) {
99       $row_set = $arg;
100
101     } elsif ('HASH' eq ref $arg) {
102       $row_set = [ $arg ];
103
104     } else {
105       $self->{form}->error('Incorrect usage -- expecting hash or array ref');
106     }
107
108     my @columns_with_default_alignment = grep { defined $self->{columns}->{$_}->{align} } keys %{ $self->{columns} };
109
110     foreach my $row (@{ $row_set }) {
111       foreach my $column (@columns_with_default_alignment) {
112         $row->{$column}          ||= { };
113         $row->{$column}->{align}   = $self->{columns}->{$column}->{align} unless (defined $row->{$column}->{align});
114       }
115
116       foreach my $field (qw(data link)) {
117         map { $row->{$_}->{$field} = [ $row->{$_}->{$field} ] if (ref $row->{$_}->{$field} ne 'ARRAY') } keys %{ $row };
118       }
119     }
120
121     push @{ $self->{data} }, $row_set;
122     $last_row_set = $row_set;
123
124     $self->{data_present} = 1;
125   }
126
127   return $last_row_set;
128 }
129
130 sub add_separator {
131   my $self = shift;
132
133   push @{ $self->{data} }, { 'type' => 'separator' };
134 }
135
136 sub add_control {
137   my $self = shift;
138   my $data = shift;
139
140   push @{ $self->{data} }, $data;
141 }
142
143 sub clear_data {
144   my $self = shift;
145
146   $self->{data}         = [];
147   $self->{data_present} = 0;
148 }
149
150 sub set_options {
151   my $self    = shift;
152   my %options = @_;
153
154   while (my ($key, $value) = each %options) {
155     if ($key eq 'pdf_export') {
156       map { $self->{options}->{pdf_export}->{$_} = $value->{$_} } keys %{ $value };
157     } else {
158       $self->{options}->{$key} = $value;
159     }
160   }
161 }
162
163 sub set_options_from_form {
164   my $self     = shift;
165
166   my $form     = $self->{form};
167   my $myconfig = $self->{myconfig};
168
169   foreach my $key (qw(output_format)) {
170     my $full_key = "report_generator_${key}";
171     $self->{options}->{$key} = $form->{$full_key} if (defined $form->{$full_key});
172   }
173
174   foreach my $format (qw(pdf csv)) {
175     my $opts = $self->{options}->{"${format}_export"};
176     foreach my $key (keys %{ $opts }) {
177       my $full_key = "report_generator_${format}_options_${key}";
178       $opts->{$key} = $key =~ /^margin/ ? $form->parse_amount($myconfig, $form->{$full_key}) : $form->{$full_key};
179     }
180   }
181 }
182
183 sub set_export_options {
184   my $self        = shift;
185
186   $self->{export} = {
187     'nextsub'       => shift,
188     'variable_list' => [ @_ ],
189   };
190 }
191
192 sub set_custom_headers {
193   my $self = shift;
194
195   if (@_) {
196     $self->{custom_headers} = [ @_ ];
197   } else {
198     delete $self->{custom_headers};
199   }
200 }
201
202 sub get_attachment_basename {
203   my $self     = shift;
204   my $filename =  $self->{options}->{attachment_basename} || 'report';
205   $filename    =~ s|.*\\||;
206   $filename    =~ s|.*/||;
207
208   return $filename;
209 }
210
211 sub generate_with_headers {
212   my $self   = shift;
213   my $format = lc $self->{options}->{output_format};
214   my $form   = $self->{form};
215
216   if (!$self->{columns}) {
217     $form->error('Incorrect usage -- no columns specified');
218   }
219
220   if ($format eq 'html') {
221     my $title      = $form->{title};
222     $form->{title} = $self->{title} if ($self->{title});
223     $form->header();
224     $form->{title} = $title;
225
226     print $self->generate_html_content();
227
228   } elsif ($format eq 'csv') {
229     my $filename = $self->get_attachment_basename();
230     print qq|content-type: text/csv\n|;
231     print qq|content-disposition: attachment; filename=${filename}.csv\n\n|;
232     $self->generate_csv_content();
233
234   } elsif ($format eq 'pdf') {
235     $self->generate_pdf_content();
236
237   } else {
238     $form->error('Incorrect usage -- unknown format (supported are HTML, CSV, PDF)');
239   }
240 }
241
242 sub get_visible_columns {
243   my $self   = shift;
244   my $format = shift;
245
246   return grep { my $c = $self->{columns}->{$_}; $c && $c->{visible} && (($c->{visible} == 1) || ($c->{visible} =~ /\Q${format}\E/i)) } @{ $self->{column_order} };
247 }
248
249 sub html_format {
250   my $self  = shift;
251   my $value = shift;
252
253   $value =  $main::locale->quote_special_chars('HTML', $value);
254   $value =~ s/\r//g;
255   $value =~ s/\n/<br>/g;
256
257   return $value;
258 }
259
260 sub prepare_html_content {
261   my $self = shift;
262
263   my ($column, $name, @column_headers);
264
265   my $opts            = $self->{options};
266   my @visible_columns = $self->get_visible_columns('HTML');
267
268   foreach $name (@visible_columns) {
269     $column = $self->{columns}->{$name};
270
271     my $header = {
272       'name'                     => $name,
273       'link'                     => $column->{link},
274       'text'                     => $column->{text},
275       'show_sort_indicator'      => $name eq $opts->{sort_indicator_column},
276       'sort_indicator_direction' => $opts->{sort_indicator_direction},
277     };
278
279     push @column_headers, $header;
280   }
281
282   my $header_rows;
283   if ($self->{custom_headers}) {
284     $header_rows = $self->{custom_headers};
285   } else {
286     $header_rows = [ \@column_headers ];
287   }
288
289   my ($outer_idx, $inner_idx) = (0, 0);
290   my $next_border_top;
291   my @rows;
292
293   foreach my $row_set (@{ $self->{data} }) {
294     if ('HASH' eq ref $row_set) {
295       if ($row_set->{type} eq 'separator') {
296         if (! scalar @rows) {
297           $next_border_top = 1;
298         } else {
299           $rows[-1]->{BORDER_BOTTOM} = 1;
300         }
301
302         next;
303       }
304
305       my $row_data = {
306         'IS_CONTROL'      => 1,
307         'IS_COLSPAN_DATA' => $row_set->{type} eq 'colspan_data',
308         'NUM_COLUMNS'     => scalar @visible_columns,
309         'BORDER_TOP'      => $next_border_top,
310         'data'            => $row_set->{data},
311       };
312
313       push @rows, $row_data;
314
315       $next_border_top = 0;
316
317       next;
318     }
319
320     $outer_idx++;
321
322     foreach my $row (@{ $row_set }) {
323       $inner_idx++;
324
325       my $output_columns = [ ];
326       my $skip_next      = 0;
327       foreach my $col_name (@visible_columns) {
328         if ($skip_next) {
329           $skip_next--;
330           next;
331         }
332
333         my $col = $row->{$col_name};
334         $col->{CELL_ROWS} = [ ];
335         foreach my $i (0 .. scalar(@{ $col->{data} }) - 1) {
336           push @{ $col->{CELL_ROWS} }, {
337             'data' => $self->html_format($col->{data}->[$i]),
338             'link' => $col->{link}->[$i],
339           };
340         }
341
342         # Force at least a &nbsp; to be displayed so that browsers
343         # will format the table cell (e.g. borders etc).
344         if (!scalar @{ $col->{CELL_ROWS} }) {
345           push @{ $col->{CELL_ROWS} }, { 'data' => '&nbsp;' };
346         } elsif ((1 == scalar @{ $col->{CELL_ROWS} }) && (!defined $col->{CELL_ROWS}->[0]->{data} || ($col->{CELL_ROWS}->[0]->{data} eq ''))) {
347           $col->{CELL_ROWS}->[0]->{data} = '&nbsp;';
348         }
349
350         push @{ $output_columns }, $col;
351         $skip_next = $col->{colspan} ? $col->{colspan} - 1 : 0;
352       }
353
354       my $row_data = {
355         'COLUMNS'       => $output_columns,
356         'outer_idx'     => $outer_idx,
357         'outer_idx_odd' => $outer_idx % 2,
358         'inner_idx'     => $inner_idx,
359         'BORDER_TOP'    => $next_border_top,
360       };
361
362       push @rows, $row_data;
363
364       $next_border_top = 0;
365     }
366   }
367
368   my @export_variables = $self->{form}->flatten_variables(@{ $self->{export}->{variable_list} });
369
370   my $allow_pdf_export = $opts->{allow_pdf_export};
371
372   eval { require PDF::API2; require PDF::Table; };
373   $allow_pdf_export |= 1 if (! $@);
374
375   my $variables = {
376     'TITLE'                => $opts->{title},
377     'TOP_INFO_TEXT'        => $self->html_format($opts->{top_info_text}),
378     'RAW_TOP_INFO_TEXT'    => $opts->{raw_top_info_text},
379     'BOTTOM_INFO_TEXT'     => $self->html_format($opts->{bottom_info_text}),
380     'RAW_BOTTOM_INFO_TEXT' => $opts->{raw_bottom_info_text},
381     'ALLOW_PDF_EXPORT'     => $allow_pdf_export,
382     'ALLOW_CSV_EXPORT'     => $opts->{allow_csv_export},
383     'SHOW_EXPORT_BUTTONS'  => ($allow_pdf_export || $opts->{allow_csv_export}) && $self->{data_present},
384     'HEADER_ROWS'          => $header_rows,
385     'NUM_COLUMNS'          => scalar @column_headers,
386     'ROWS'                 => \@rows,
387     'EXPORT_VARIABLES'     => \@export_variables,
388     'EXPORT_VARIABLE_LIST' => join(' ', @{ $self->{export}->{variable_list} }),
389     'EXPORT_NEXTSUB'       => $self->{export}->{nextsub},
390     'DATA_PRESENT'         => $self->{data_present},
391   };
392
393   return $variables;
394 }
395
396 sub generate_html_content {
397   my $self      = shift;
398   my $variables = $self->prepare_html_content();
399
400   return $self->{form}->parse_html_template($self->{options}->{html_template}, $variables);
401 }
402
403 sub _cm2bp {
404   # 1 bp = 1/72 in
405   # 1 in = 2.54 cm
406   return $_[0] * 72 / 2.54;
407 }
408
409 sub generate_pdf_content {
410   eval {
411     require PDF::API2;
412     require PDF::Table;
413   };
414
415   my $self       = shift;
416   my $variables  = $self->prepare_html_content();
417   my $form       = $self->{form};
418   my $myconfig   = $self->{myconfig};
419
420   my $opts       = $self->{options};
421   my $pdfopts    = $opts->{pdf_export};
422
423   my (@data, @column_props, @cell_props);
424
425   my ($data_row, $cell_props_row);
426   my @visible_columns = $self->get_visible_columns('HTML');
427   my $num_columns     = scalar @visible_columns;
428   my $num_header_rows = 1;
429
430   foreach $name (@visible_columns) {
431     push @column_props, { 'justify' => $self->{columns}->{$name}->{align} eq 'right' ? 'right' : 'left' };
432   }
433
434   if (!$self->{custom_headers}) {
435     $data_row       = [];
436     $cell_props_row = [];
437     push @data,       $data_row;
438     push @cell_props, $cell_props_row;
439
440     foreach $name (@visible_columns) {
441       $column = $self->{columns}->{$name};
442
443       push @{ $data_row },       $column->{text};
444       push @{ $cell_props_row }, {};
445     }
446
447   } else {
448     $num_header_rows = scalar @{ $self->{custom_headers} };
449
450     foreach my $custom_header_row (@{ $self->{custom_headers} }) {
451       $data_row       = [];
452       $cell_props_row = [];
453       push @data,       $data_row;
454       push @cell_props, $cell_props_row;
455
456       foreach my $custom_header_col (@{ $custom_header_row }) {
457         push @{ $data_row }, $custom_header_col->{text};
458
459         my $num_output  = ($custom_header_col->{colspan} * 1 > 1) ? $custom_header_col->{colspan} : 1;
460         if ($num_output > 1) {
461           push @{ $data_row },       ('') x ($num_output - 1);
462           push @{ $cell_props_row }, { 'colspan' => $num_output };
463           push @{ $cell_props_row }, ({ }) x ($num_output - 1);
464
465         } else {
466           push @{ $cell_props_row }, {};
467         }
468       }
469     }
470   }
471
472   foreach my $row_set (@{ $self->{data} }) {
473     if ('HASH' eq ref $row_set) {
474       if ($row_set->{type} eq 'colspan_data') {
475         push @data, [ $row_set->{data} ];
476
477         $cell_props_row = [];
478         push @cell_props, $cell_props_row;
479
480         foreach (0 .. $num_columns - 1) {
481           push @{ $cell_props_row }, { 'background_color' => '#666666',
482                                        'font_color'       => '#ffffff',
483                                        'colspan'          => $_ == 0 ? -1 : undef, };
484         }
485       }
486       next;
487     }
488
489     foreach my $row (@{ $row_set }) {
490       $data_row       = [];
491       $cell_props_row = [];
492
493       push @data,       $data_row;
494       push @cell_props, $cell_props_row;
495
496       my $col_idx = 0;
497       foreach my $col_name (@visible_columns) {
498         my $col = $row->{$col_name};
499         push @{ $data_row }, join("\n", @{ $col->{data} });
500
501         $column_props[$col_idx]->{justify} = 'right' if ($col->{align} eq 'right');
502
503         my $cell_props = { };
504         push @{ $cell_props_row }, $cell_props;
505
506         if ($col->{colspan} && $col->{colspan} > 1) {
507           $cell_props->{colspan} = $col->{colspan};
508         }
509
510         $col_idx++;
511       }
512     }
513   }
514
515   foreach my $i (0 .. scalar(@data) - 1) {
516     my $aref             = $data[$i];
517     my $num_columns_here = scalar @{ $aref };
518
519     if ($num_columns_here < $num_columns) {
520       push @{ $aref }, ('') x ($num_columns - $num_columns_here);
521     } elsif ($num_columns_here > $num_columns) {
522       splice @{ $aref }, $num_columns;
523     }
524   }
525
526   my $papersizes = {
527     'a3'         => [ 842, 1190 ],
528     'a4'         => [ 595,  842 ],
529     'a5'         => [ 420,  595 ],
530     'letter'     => [ 612,  792 ],
531     'legal'      => [ 612, 1008 ],
532   };
533
534   my %supported_fonts = map { $_ => 1 } qw(courier georgia helvetica times verdana);
535
536   my $paper_size  = defined $pdfopts->{paper_size} && defined $papersizes->{lc $pdfopts->{paper_size}} ? lc $pdfopts->{paper_size} : 'a4';
537   my ($paper_width, $paper_height);
538
539   if (lc $pdfopts->{orientation} eq 'landscape') {
540     ($paper_width, $paper_height) = @{$papersizes->{$paper_size}}[1, 0];
541   } else {
542     ($paper_width, $paper_height) = @{$papersizes->{$paper_size}}[0, 1];
543   }
544
545   my $margin_top        = _cm2bp($pdfopts->{margin_top}    || 1.5);
546   my $margin_bottom     = _cm2bp($pdfopts->{margin_bottom} || 1.5);
547   my $margin_left       = _cm2bp($pdfopts->{margin_left}   || 1.5);
548   my $margin_right      = _cm2bp($pdfopts->{margin_right}  || 1.5);
549
550   my $table             = PDF::Table->new();
551   my $pdf               = PDF::API2->new();
552   my $page              = $pdf->page();
553
554   $pdf->mediabox($paper_width, $paper_height);
555
556   my $font              = $pdf->corefont(defined $pdfopts->{font_name} && $supported_fonts{lc $pdfopts->{font_name}} ? ucfirst $pdfopts->{font_name} : 'Verdana',
557                                          '-encoding' => $main::dbcharset || 'ISO-8859-15');
558   my $font_size         = $pdfopts->{font_size} || 7;
559   my $title_font_size   = $font_size + 1;
560   my $padding           = 1;
561   my $font_height       = $font_size + 2 * $padding;
562   my $title_font_height = $font_size + 2 * $padding;
563
564   my $header_height     = 2 * $title_font_height if ($opts->{title});
565   my $footer_height     = 2 * $font_height       if ($pdfopts->{number});
566
567   my $top_text_height   = 0;
568
569   if ($self->{options}->{top_info_text}) {
570     my $top_text     =  $self->{options}->{top_info_text};
571     $top_text        =~ s/\r//g;
572     $top_text        =~ s/\n+$//;
573
574     my @lines        =  split m/\n/, $top_text;
575     $top_text_height =  $font_height * scalar @lines;
576
577     foreach my $line_no (0 .. scalar(@lines) - 1) {
578       my $y_pos    = $paper_height - $margin_top - $header_height - $line_no * $font_height;
579       my $text_obj = $page->text();
580
581       $text_obj->font($font, $font_size);
582       $text_obj->translate($margin_left, $y_pos);
583       $text_obj->text($lines[$line_no]);
584     }
585   }
586
587   $table->table($pdf,
588                 $page,
589                 \@data,
590                 'x'                     => $margin_left,
591                 'w'                     => $paper_width - $margin_left - $margin_right,
592                 'start_y'               => $paper_height - $margin_top                  - $header_height                  - $top_text_height,
593                 'next_y'                => $paper_height - $margin_top                  - $header_height,
594                 'start_h'               => $paper_height - $margin_top - $margin_bottom - $header_height - $footer_height - $top_text_height,
595                 'next_h'                => $paper_height - $margin_top - $margin_bottom - $header_height - $footer_height,
596                 'padding'               => 1,
597                 'background_color_odd'  => '#ffffff',
598                 'background_color_even' => '#eeeeee',
599                 'font'                  => $font,
600                 'font_size'             => $font_size,
601                 'font_color'            => '#000000',
602                 'num_header_rows'       => $num_header_rows,
603                 'header_props'          => {
604                   'bg_color'            => '#ffffff',
605                   'repeat'              => 1,
606                   'font_color'          => '#000000',
607                 },
608                 'column_props'          => \@column_props,
609                 'cell_props'            => \@cell_props,
610     );
611
612   foreach my $page_num (1..$pdf->pages()) {
613     my $curpage  = $pdf->openpage($page_num);
614
615     if ($pdfopts->{number}) {
616       my $label    = $main::locale->text("Page #1/#2", $page_num, $pdf->pages());
617       my $text_obj = $curpage->text();
618
619       $text_obj->font($font, $font_size);
620       $text_obj->translate(($paper_width - $margin_left - $margin_right) / 2 + $margin_left - $text_obj->advancewidth($label) / 2, $margin_bottom);
621       $text_obj->text($label);
622     }
623
624     if ($opts->{title}) {
625       my $text_obj = $curpage->text();
626
627       $text_obj->font($font, $title_font_size);
628       $text_obj->translate(($paper_width - $margin_left - $margin_right) / 2 + $margin_left - $text_obj->advancewidth($opts->{title}) / 2,
629                            $paper_height - $margin_top);
630       $text_obj->text($opts->{title}, '-underline' => 1);
631     }
632   }
633
634   my $content = $pdf->stringify();
635
636   my $printer_command;
637   if ($pdfopts->{print} && $pdfopts->{printer_id}) {
638     $form->{printer_id} = $pdfopts->{printer_id};
639     $form->get_printer_code($myconfig);
640     $printer_command = $form->{printer_command};
641   }
642
643   if ($printer_command) {
644     $self->_print_content('printer_command' => $printer_command,
645                           'content'         => $content,
646                           'copies'          => $pdfopts->{copies});
647     $form->{report_generator_printed} = 1;
648
649   } else {
650     my $filename = $self->get_attachment_basename();
651
652     print qq|content-type: application/pdf\n|;
653     print qq|content-disposition: attachment; filename=${filename}.pdf\n\n|;
654
655     print $content;
656   }
657 }
658
659 sub verify_paper_size {
660   my $self                 = shift;
661   my $requested_paper_size = lc shift;
662   my $default_paper_size   = shift;
663
664   my %allowed_paper_sizes  = map { $_ => 1 } qw(a3 a4 a5 letter legal);
665
666   return $allowed_paper_sizes{$requested_paper_size} ? $requested_paper_size : $default_paper_size;
667 }
668
669 sub _print_content {
670   my $self   = shift;
671   my %params = @_;
672
673   foreach my $i (1 .. max $params{copies}, 1) {
674     my $printer = IO::File->new("| $params{printer_command}");
675     $main::form->error($main::locale->text('Could not spawn the printer command.')) if (!$printer);
676     $printer->print($params{content});
677     $printer->close();
678   }
679 }
680
681 sub unescape_string {
682   my $self  = shift;
683   my $text  = shift;
684   my $iconv = $main::locale->{iconv};
685
686   $text     = $main::locale->unquote_special_chars('HTML', $text);
687   $text     = $main::locale->{iconv}->convert($text) if ($main::locale->{iconv});
688
689   return $text;
690 }
691
692 sub generate_csv_content {
693   my $self = shift;
694
695   my %valid_sep_chars    = (';' => ';', ',' => ',', ':' => ':', 'TAB' => "\t");
696   my %valid_escape_chars = ('"' => 1, "'" => 1);
697   my %valid_quote_chars  = ('"' => 1, "'" => 1);
698
699   my $opts        = $self->{options}->{csv_export};
700   my $eol         = $opts->{eol_style} eq 'DOS'               ? "\r\n"                              : "\n";
701   my $sep_char    = $valid_sep_chars{$opts->{sep_char}}       ? $valid_sep_chars{$opts->{sep_char}} : ';';
702   my $escape_char = $valid_escape_chars{$opts->{escape_char}} ? $opts->{escape_char}                : '"';
703   my $quote_char  = $valid_quote_chars{$opts->{quote_char}}   ? $opts->{quote_char}                 : '"';
704
705   $escape_char    = $quote_char if ($opts->{escape_char} eq 'QUOTE_CHAR');
706
707   my $csv = Text::CSV_XS->new({ 'binary'      => 1,
708                                 'sep_char'    => $sep_char,
709                                 'escape_char' => $escape_char,
710                                 'quote_char'  => $quote_char,
711                                 'eol'         => $eol, });
712
713   my $stdout          = wraphandle(\*STDOUT);
714   my @visible_columns = $self->get_visible_columns('CSV');
715
716   if ($opts->{headers}) {
717     if (!$self->{custom_headers}) {
718       $csv->print($stdout, [ map { $self->unescape_string($self->{columns}->{$_}->{text}) } @visible_columns ]);
719
720     } else {
721       foreach my $row (@{ $self->{custom_headers} }) {
722         my $fields = [ ];
723
724         foreach my $col (@{ $row }) {
725           my $num_output = ($col->{colspan} && ($col->{colspan} > 1)) ? $col->{colspan} : 1;
726           push @{ $fields }, ($self->unescape_string($col->{text})) x $num_output;
727         }
728
729         $csv->print($stdout, $fields);
730       }
731     }
732   }
733
734   foreach my $row_set (@{ $self->{data} }) {
735     next if ('ARRAY' ne ref $row_set);
736     foreach my $row (@{ $row_set }) {
737       my @data;
738       my $skip_next = 0;
739       foreach my $col (@visible_columns) {
740         if ($skip_next) {
741           $skip_next--;
742           next;
743         }
744
745         my $num_output = ($col->{colspan} && ($col->{colspan} > 1)) ? $col->{colspan} : 1;
746         $skip_next     = $num_output - 1;
747
748         push @data, join($eol, map { s/\r?\n/$eol/g; $_ } @{ $row->{$col}->{data} });
749         push @data, ('') x $skip_next if ($skip_next);
750       }
751
752       $csv->print($stdout, \@data);
753     }
754   }
755 }
756
757 1;
758
759 __END__
760
761 =head1 NAME
762
763 SL::ReportGenerator.pm: the Lx-Office way of getting data in shape
764
765 =head1 SYNOPSIS
766
767   my $report = SL::ReportGenerator->new(\%myconfig, $form);
768      $report->set_options(%options);                         # optional
769      $report->set_columns(%column_defs);
770      $report->set_sort_indicator($column, $direction);       # optional
771      $report->add_data($row1, $row2, @more_rows);
772      $report->generate_with_headers();
773
774 This creates a report object, sets a few columns, adds some data and generates a standard report. 
775 Sorting of columns will be alphabetic, and options will be set to their defaults.
776 The report will be printed including table headers, html headers and http headers.
777
778 =head1 DESCRIPTION
779
780 Imagine the following scenario:
781 There's a simple form, which loads some data from the database, and needs to print it out. You write a template for it.
782 Then there may be more than one line. You add a loop in the template.
783 Then there are some options made by the user, such as hidden columns. You add more to the template.
784 Then it lacks usability. You want it to be able to sort the data. You add code for that.
785 Then there are too many results, you need pagination, you want to print or export that data..... and so on.
786
787 The ReportGenerator class was designed because this exact scenario happened about half a dozen times in Lx-Office. 
788 It's purpose is to manage all those formating, culling, sorting, and templating. 
789 Which makes it almost as complicated to use as doing the work for yourself.
790
791 =head1 FUNCTIONS
792
793 =over 4
794
795 =item new \%myconfig,$form,%options
796
797 Creates a new ReportGenerator object, sets all given options, and returns it.
798
799 =item set_columns %columns
800
801 Sets the columns available to this report.
802
803 =item set_column_order @columns
804
805 Sets the order of columns. Any columns not present here are appended in alphabetic order.
806
807 =item set_sort_indicator $column,$direction
808
809 Sets sorting ot the table by specifying a column and a direction, where the direction will be evaluated to ascending if true.
810 Note that this is only for displaying. The data has to be presented already sorted.
811
812 =item add_data \@data
813
814 =item add_data \%data
815
816 Adds data to the report. A given hash_ref is interpreted as a single line of data, every array_ref as a collection of lines. 
817 Every line will be expected to be in a kay => value format. Note that the rows have to be already sorted. 
818 ReportGenerator does only colum sorting on its own, and provides links to sorting and visual cue as to which column was sorted by.
819
820 =item add_separator
821
822 Adds a separator line to the report.
823
824 =item add_control \%data
825
826 Adds a control element to the data. Control elements are an experimental feature to add functionality to a report the regular data cannot.
827 Every control element needs to set IS_CONTROL_DATA, in order to be recongnized by the template. 
828 Currently the only control element is a colspan element, which can be used as a mini header further down the report.
829
830 =item clear_data
831
832 Deletes all data filled into the report, but keeps options set.
833
834 =item set_options %options
835
836 Sets options. For an incomplete list of options, see section configuration.
837
838 =item set_options_from_form
839
840 Tries to import options from the $form object given at creation
841
842 =item set_export_options $next_sub,@variable_list
843
844 Sets next_sub and additional variables needed for export.
845
846 =item get_attachment_basename
847
848 Returns the set attachment_basename option, or 'report' if nothing was set. See configuration for the option.
849
850 =item generate_with_headers
851
852 Parses the report, adds headers and prints it out. Headers depend on the option 'output_format', 
853 for example 'HTML' will add proper table headers, html headers and http headers. See configuration for this option.
854
855 =item get_visible_columns $format
856
857 Returns a list of columns that will be visible in the report after considering all options or match the given format.
858
859 =item html_format $value
860
861 Escapes HTML characters in $value and substitutes newlines with '<br>'. Returns the escaped $value.
862
863 =item prepare_html_content $column,$name,@column_headers
864
865 Parses the data, and sets internal data needed for certain output format. Must be called once before the template is invoked. 
866 Should not be called extrenally, since all render and generate functions invoke it anyway.
867  
868 =item generate_html_content
869
870 The html generation function. Is invoked by generate_with_headers.
871
872 =item generate_pdf_content
873
874 The PDF generation function. It is invoked by generate_with_headers, tests whether or not the Perl module PDF::API2 is installed and calls render_pdf_with_pdf_api2 if it is and render_pdf_with_html2ps otherwise.
875
876 =item generate_csv_content
877
878 The CSV generation function. Uses XS_CSV to parse the information into csv.
879
880 =item render_pdf_with_pdf_api2
881
882 PDF render function using the Perl module PDF::API2.
883
884 =item render_pdf_with_html2ps
885
886 PDF render function using the external application html2ps.
887
888 =back
889
890 =head1 CONFIGURATION
891
892 These are known options and their defaults. Options for pdf export and csv export need to be set as a hashref inside the export option.
893
894 =head2 General Options
895
896 =over 4
897
898 =item std_column_visibility
899
900 Standard column visibility. Used if no visibility is set. Use this to save the trouble of enabling every column. Default is no.
901
902 =item output_format
903
904 Output format. Used by generate_with_headers to determine the format. Supported options are HTML, CSV, and PDF. Default is HTML.
905
906 =item allow_pdf_export
907
908 Used to determine if a button for PDF export should be displayed. Default is yes. The PDF button is hidden if neither the Perl module PDF::API2 nor the external applications html2ps and Ghostscript are available regardless of this parameter's value.
909
910 =item allow_csv_export
911
912 Used to determine if a button for CSV export should be displayed. Default is yes.
913
914 =item html_template
915
916 The template to be used for HTML reports. Default is 'report_generator/html_report'.
917
918 =back
919
920 =head2 PDF Options
921
922 =over 4
923
924 =item paper_size
925
926 Paper size. Default is a4. Supported paper sizes are a3, a4, a5, letter and legal.
927
928 =item orientation (landscape)
929
930 Landscape or portrait. Default is landscape.
931
932 =item font_name 
933
934 Default is Verdana. Supported font names are Courier, Georgia, Helvetica, Times and Verdana. This option only affects the rendering with PDF::API2.
935
936 =item font_size
937
938 Default is 7. This option only affects the rendering with PDF::API2.
939
940 =item margin_top
941
942 =item margin_left
943
944 =item margin_bottom
945
946 =item margin_right
947
948 The paper margins in cm. They all default to 1.5.
949
950 =item number
951
952 Set to a true value if the pages should be numbered. Default is 1.
953
954 =item print
955
956 If set then the resulting PDF will be output to a printer. If not it will be downloaded by the user. Default is no.
957
958 =item printer_id
959
960 Default 0.
961
962 =item copies
963
964 Default 1.
965
966 =back
967
968 =head2 CSV Options
969
970 =over 4
971
972 =item quote_char
973
974 Character to enclose entries. Default is double quote (").
975
976 =item sep_char
977
978 Character to separate entries. Default is semicolon (;).
979
980 =item escape_char
981
982 Character to escape the quote_char. Default is double quote (").
983
984 =item eol_style
985
986 End of line style. Default is Unix.
987
988 =item headers
989
990 Include headers? Default is yes.
991
992 =back
993
994 =head1 SEE ALO
995
996 C<Template.pm>
997
998 =head1 MODULE AUTHORS
999
1000 Moritz Bunkus E<lt>mbunkus@linet-services.deE<gt>
1001
1002 L<http://linet-services.de>