FS/FS/Template_Mixin.pm

   1 package FS::Template_Mixin;
   2
   3 use strict;
   4 use vars qw( $DEBUG $me
   5              $money_char
   6              $date_format
   7            );
   8              # but NOT $conf
   9 use vars qw( $invoice_lines @buf ); #yuck
  10 use List::Util qw(sum);
  11 use Date::Format;
  12 use Date::Language;
  13 use Text::Template 1.20;
  14 use File::Temp 0.14;
  15 use HTML::Entities;
  16 use Locale::Country;
  17 use Cwd;
  18 use FS::UID;
  19 use FS::Record qw( qsearch qsearchs );
  20 use FS::Conf;
  21 use FS::Misc qw( generate_ps generate_pdf );
  22 use FS::pkg_category;
  23 use FS::pkg_class;
  24 use FS::invoice_mode;
  25 use FS::L10N;
  26
  27 $DEBUG = 0;
  28 $me = '[FS::Template_Mixin]';
  29 FS::UID->install_callback( sub {
  30   my $conf = new FS::Conf; #global
  31   $money_char  = $conf->config('money_char')  || '$';
  32   $date_format = $conf->config('date_format') || '%x'; #/YY
  33 } );
  34
  35 =item conf [ MODE ]
  36
  37 Returns a configuration handle (L<FS::Conf>) set to the customer's locale.
  38
  39 If the "mode" pseudo-field is set on the object, the configuration handle
  40 will be an L<FS::invoice_conf> for that invoice mode (and the customer's
  41 locale).
  42
  43 =cut
  44
  45 sub conf {
  46   my $self = shift;
  47   my $mode = $self->get('mode');
  48   if ($self->{_conf} and !defined($mode)) {
  49     return $self->{_conf};
  50   }
  51
  52   my $cust_main = $self->cust_main;
  53   my $locale = $cust_main ? $cust_main->locale : '';
  54   my $conf;
  55   if ( $mode ) {
  56     if ( ref $mode and $mode->isa('FS::invoice_mode') ) {
  57       $mode = $mode->modenum;
  58     } elsif ( $mode =~ /\D/ ) {
  59       die "invalid invoice mode $mode";
  60     }
  61     $conf = qsearchs('invoice_conf', { modenum => $mode, locale => $locale });
  62     if (!$conf) {
  63       $conf = qsearchs('invoice_conf', { modenum => $mode, locale => '' });
  64       # it doesn't have a locale, but system conf still might
  65       $conf->set('locale' => $locale) if $conf;
  66     }
  67   }
  68   # if $mode is unspecified, or if there is no invoice_conf matching this mode
  69   # and locale, then use the system config only (but with the locale)
  70   $conf ||= FS::Conf->new({ 'locale' => $locale });
  71   # cache it
  72   return $self->{_conf} = $conf;
  73 }
  74
  75 =item print_text OPTIONS
  76
  77 Returns an text invoice, as a list of lines.
  78
  79 Options can be passed as a hash.
  80
  81 I<time>, if specified, is used to control the printing of overdue messages.  The
  82 default is now.  It isn't the date of the invoice; that's the `_date' field.
  83 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
  84 L<Time::Local> and L<Date::Parse> for conversion functions.
  85
  86 I<template>, if specified, is the name of a suffix for alternate invoices.
  87
  88 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
  89
  90 =cut
  91
  92 sub print_text {
  93   my $self = shift;
  94   my %params;
  95   if ( ref($_[0]) ) {
  96     %params = %{ shift() };
  97   } else {
  98     %params = @_;
  99   }
 100
 101   $params{'format'} = 'template'; # for some reason
 102
 103   $self->print_generic( %params );
 104 }
 105
 106 =item print_latex HASHREF
 107
 108 Internal method - returns a filename of a filled-in LaTeX template for this
 109 invoice (Note: add ".tex" to get the actual filename), and a filename of
 110 an associated logo (with the .eps extension included).
 111
 112 See print_ps and print_pdf for methods that return PostScript and PDF output.
 113
 114 Options can be passed as a hash.
 115
 116 I<time>, if specified, is used to control the printing of overdue messages.  The
 117 default is now.  It isn't the date of the invoice; that's the `_date' field.
 118 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
 119 L<Time::Local> and L<Date::Parse> for conversion functions.
 120
 121 I<template>, if specified, is the name of a suffix for alternate invoices.
 122 This is strongly deprecated; see L<FS::invoice_conf> for the right way to
 123 customize invoice templates for different purposes.
 124
 125 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
 126
 127 =cut
 128
 129 sub print_latex {
 130   my $self = shift;
 131   my %params;
 132
 133   if ( ref($_[0]) ) {
 134     %params = %{ shift() };
 135   } else {
 136     %params = @_;
 137   }
 138
 139   $params{'format'} = 'latex';
 140   my $conf = $self->conf;
 141
 142   # this needs to go away
 143   my $template = $params{'template'};
 144   # and this especially
 145   $template ||= $self->_agent_template
 146     if $self->can('_agent_template');
 147
 148   my $pkey = $self->primary_key;
 149   my $tmp_template = $self->table. '.'. $self->$pkey. '.XXXXXXXX';
 150
 151   my $dir = $FS::UID::conf_dir. "/cache.". $FS::UID::datasrc;
 152   my $lh = new File::Temp(
 153     TEMPLATE => $tmp_template,
 154     DIR      => $dir,
 155     SUFFIX   => '.eps',
 156     UNLINK   => 0,
 157   ) or die "can't open temp file: $!\n";
 158
 159   my $agentnum = $self->agentnum;
 160
 161   if ( $template && $conf->exists("logo_${template}.eps", $agentnum) ) {
 162     print $lh $conf->config_binary("logo_${template}.eps", $agentnum)
 163       or die "can't write temp file: $!\n";
 164   } else {
 165     print $lh $conf->config_binary('logo.eps', $agentnum)
 166       or die "can't write temp file: $!\n";
 167   }
 168   close $lh;
 169   $params{'logo_file'} = $lh->filename;
 170
 171   if( $conf->exists('invoice-barcode')
 172         && $self->can('invoice_barcode')
 173         && $self->invnum ) { # don't try to barcode statements
 174       my $png_file = $self->invoice_barcode($dir);
 175       my $eps_file = $png_file;
 176       $eps_file =~ s/\.png$/.eps/g;
 177       $png_file =~ /(barcode.*png)/;
 178       $png_file = $1;
 179       $eps_file =~ /(barcode.*eps)/;
 180       $eps_file = $1;
 181
 182       my $curr_dir = cwd();
 183       chdir($dir);
 184       # after painfuly long experimentation, it was determined that sam2p won't
 185       # accept : and other chars in the path, no matter how hard I tried to
 186       # escape them, hence the chdir (and chdir back, just to be safe)
 187       system('sam2p', '-j:quiet', $png_file, 'EPS:', $eps_file ) == 0
 188         or die "sam2p failed: $!\n";
 189       unlink($png_file);
 190       chdir($curr_dir);
 191
 192       $params{'barcode_file'} = $eps_file;
 193   }
 194
 195   my @filled_in = $self->print_generic( %params );
 196
 197   my $fh = new File::Temp( TEMPLATE => $tmp_template,
 198                            DIR      => $dir,
 199                            SUFFIX   => '.tex',
 200                            UNLINK   => 0,
 201                          ) or die "can't open temp file: $!\n";
 202   binmode($fh, ':utf8'); # language support
 203   print $fh join('', @filled_in );
 204   close $fh;
 205
 206   $fh->filename =~ /^(.*).tex$/ or die "unparsable filename: ". $fh->filename;
 207   return ($1, $params{'logo_file'}, $params{'barcode_file'});
 208
 209 }
 210
 211 sub agentnum {
 212   my $self = shift;
 213   my $cust_main = $self->cust_main;
 214   $cust_main ? $cust_main->agentnum : $self->prospect_main->agentnum;
 215 }
 216
 217 =item print_generic OPTION => VALUE ...
 218
 219 Internal method - returns a filled-in template for this invoice as a scalar.
 220
 221 See print_ps and print_pdf for methods that return PostScript and PDF output.
 222
 223 Required options
 224
 225 =over 4
 226
 227 =item format
 228
 229 The B<format> option is required and should be set to html, latex (print and PDF) or template (plaintext).
 230
 231 =back
 232
 233 Additional options
 234
 235 =over 4
 236
 237 =item notice_name
 238
 239 Overrides "Invoice" as the name of the sent document.
 240
 241 =item today
 242
 243 Used to control the printing of overdue messages.  The
 244 default is now.  It isn't the date of the invoice; that's the `_date' field.
 245 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
 246 L<Time::Local> and L<Date::Parse> for conversion functions.
 247
 248 =item logo_file
 249
 250 Logo file (path to temporary EPS file on the local filesystem)
 251
 252 =item cid
 253
 254 CID for inline (emailed) images (logo)
 255
 256 =item locale
 257
 258 Override customer's locale
 259
 260 =item unsquelch_cdr
 261
 262 Overrides any per customer cdr squelching when true
 263
 264 =item no_number
 265
 266 Supress the (invoice, quotation, statement, etc.) number
 267
 268 =item no_date
 269
 270 Supress the date
 271
 272 =item no_coupon
 273
 274 Supress the payment coupon
 275
 276 =item barcode_file
 277
 278 Barcode file (path to temporary EPS file on the local filesystem)
 279
 280 =item barcode_img
 281
 282 Flag indicating the barcode image should be a link (normal HTML dipaly)
 283
 284 =item barcode_cid
 285
 286 Barcode CID for inline (emailed) images
 287
 288 =item preref_callback
 289
 290 Coderef run for each line item, code should return HTML to be displayed
 291 before that line item (quotations only)
 292
 293 =item template
 294
 295 Dprecated.  Used as a suffix for a configuration template.  Please
 296 don't use this, it deprecated in favor of more flexible alternatives.
 297
 298 =back
 299
 300 =cut
 301
 302 #what's with all the sprintf('%10.2f')'s in here?  will it cause any
 303 # (alignment in text invoice?) problems to change them all to '%.2f' ?
 304 # yes: fixed width/plain text printing will be borked
 305 sub print_generic {
 306   my( $self, %params ) = @_;
 307   my $conf = $self->conf;
 308
 309   my $today = $params{today} ? $params{today} : time;
 310   warn "$me print_generic called on $self with suffix $params{template}\n"
 311     if $DEBUG;
 312
 313   my $format = $params{format};
 314   die "Unknown format: $format"
 315     unless $format =~ /^(latex|html|template)$/;
 316
 317   my $cust_main = $self->cust_main || $self->prospect_main;
 318   $cust_main->payname( $cust_main->first. ' '. $cust_main->getfield('last') )
 319     unless $cust_main->payname
 320         && $cust_main->payby !~ /^(CARD|DCRD|CHEK|DCHK)$/;
 321
 322   my $locale = $params{'locale'} || $cust_main->locale;
 323
 324   my %delimiters = ( 'latex'    => [ '[@--', '--@]' ],
 325                      'html'     => [ '<%=', '%>' ],
 326                      'template' => [ '{', '}' ],
 327                    );
 328
 329   warn "$me print_generic creating template\n"
 330     if $DEBUG > 1;
 331
 332   # set the notice name here, and nowhere else.
 333   my $notice_name =  $params{notice_name}
 334                   || $conf->config('notice_name')
 335                   || $self->notice_name;
 336
 337   #create the template
 338   my $template = $params{template} ? $params{template} : $self->_agent_template;
 339   my $templatefile = $self->template_conf. $format;
 340   $templatefile .= "_$template"
 341     if length($template) && $conf->exists($templatefile."_$template");
 342
 343   # the base template
 344   my @invoice_template = map "$_\n", $conf->config($templatefile)
 345     or die "cannot load config data $templatefile";
 346
 347   if ( $format eq 'latex' && grep { /^%%Detail/ } @invoice_template ) {
 348     #change this to a die when the old code is removed
 349     # it's been almost ten years, changing it to a die.
 350     die "old-style invoice template $templatefile; ".
 351          "patch with conf/invoice_latex.diff or use new conf/invoice_latex*\n";
 352          #$old_latex = 'true';
 353          #@invoice_template = _translate_old_latex_format(@invoice_template);
 354   }
 355
 356   warn "$me print_generic creating T:T object\n"
 357     if $DEBUG > 1;
 358
 359   my $text_template = new Text::Template(
 360     TYPE => 'ARRAY',
 361     SOURCE => \@invoice_template,
 362     DELIMITERS => $delimiters{$format},
 363   );
 364
 365   warn "$me print_generic compiling T:T object\n"
 366     if $DEBUG > 1;
 367
 368   $text_template->compile()
 369     or die "Can't compile $templatefile: $Text::Template::ERROR\n";
 370
 371
 372   # additional substitution could possibly cause breakage in existing templates
 373   my %convert_maps = (
 374     'latex' => {
 375                  'notes'         => sub { map "$_", @_ },
 376                  'footer'        => sub { map "$_", @_ },
 377                  'smallfooter'   => sub { map "$_", @_ },
 378                  'returnaddress' => sub { map "$_", @_ },
 379                  'coupon'        => sub { map "$_", @_ },
 380                  'summary'       => sub { map "$_", @_ },
 381                },
 382     'html'  => {
 383                  'notes' =>
 384                    sub {
 385                      map {
 386                        s/%%(.*)$/<!-- $1 -->/g;
 387                        s/\\section\*\{\\textsc\{(.)(.*)\}\}/<p><b><font size="+1">$1<\/font>\U$2<\/b>/g;
 388                        s/\\begin\{enumerate\}/<ol>/g;
 389                        s/\\item /  <li>/g;
 390                        s/\\end\{enumerate\}/<\/ol>/g;
 391                        s/\\textbf\{(.*)\}/<b>$1<\/b>/g;
 392                        s/\\\\\*/<br>/g;
 393                        s/\\dollar ?/\$/g;
 394                        s/\\#/#/g;
 395                        s/~/&nbsp;/g;
 396                        $_;
 397                      }  @_
 398                    },
 399                  'footer' =>
 400                    sub { map { s/~/&nbsp;/g; s/\\\\\*?\s*$/<BR>/; $_; } @_ },
 401                  'smallfooter' =>
 402                    sub { map { s/~/&nbsp;/g; s/\\\\\*?\s*$/<BR>/; $_; } @_ },
 403                  'returnaddress' =>
 404                    sub {
 405                      map {
 406                        s/~/&nbsp;/g;
 407                        s/\\\\\*?\s*$/<BR>/;
 408                        s/\\hyphenation\{[\w\s\-]+}//;
 409                        s/\\([&])/$1/g;
 410                        $_;
 411                      }  @_
 412                    },
 413                  'coupon'        => sub { "" },
 414                  'summary'       => sub { "" },
 415                },
 416     'template' => {
 417                  'notes' =>
 418                    sub {
 419                      map {
 420                        s/%%.*$//g;
 421                        s/\\section\*\{\\textsc\{(.*)\}\}/\U$1/g;
 422                        s/\\begin\{enumerate\}//g;
 423                        s/\\item /  * /g;
 424                        s/\\end\{enumerate\}//g;
 425                        s/\\textbf\{(.*)\}/$1/g;
 426                        s/\\\\\*/ /;
 427                        s/\\dollar ?/\$/g;
 428                        $_;
 429                      }  @_
 430                    },
 431                  'footer' =>
 432                    sub { map { s/~/ /g; s/\\\\\*?\s*$/\n/; $_; } @_ },
 433                  'smallfooter' =>
 434                    sub { map { s/~/ /g; s/\\\\\*?\s*$/\n/; $_; } @_ },
 435                  'returnaddress' =>
 436                    sub {
 437                      map {
 438                        s/~/ /g;
 439                        s/\\\\\*?\s*$/\n/;             # dubious
 440                        s/\\hyphenation\{[\w\s\-]+}//;
 441                        $_;
 442                      }  @_
 443                    },
 444                  'coupon'        => sub { "" },
 445                  'summary'       => sub { "" },
 446                },
 447   );
 448
 449
 450   # hashes for differing output formats
 451   my %nbsps = ( 'latex'    => '~',
 452                 'html'     => '',    # '&nbps;' would be nice
 453                 'template' => '',    # not used
 454               );
 455   my $nbsp = $nbsps{$format};
 456
 457   my %escape_functions = ( 'latex'    => \&_latex_escape,
 458                            'html'     => \&_html_escape_nbsp,#\&encode_entities,
 459                            'template' => sub { shift },
 460                          );
 461   my $escape_function = $escape_functions{$format};
 462   my $escape_function_nonbsp = ($format eq 'html')
 463                                  ? \&_html_escape : $escape_function;
 464
 465   my %newline_tokens = (  'latex'     => '\\\\',
 466                           'html'      => '<br>',
 467                           'template'  => "\n",
 468                         );
 469   my $newline_token = $newline_tokens{$format};
 470
 471   warn "$me generating template variables\n"
 472     if $DEBUG > 1;
 473
 474   # generate template variables
 475   my $returnaddress;
 476
 477   if (
 478          defined( $conf->config_orbase( "invoice_${format}returnaddress",
 479                                         $template
 480                                       )
 481                 )
 482        && length( $conf->config_orbase( "invoice_${format}returnaddress",
 483                                         $template
 484                                       )
 485                 )
 486   ) {
 487
 488     $returnaddress = join("\n",
 489       $conf->config_orbase("invoice_${format}returnaddress", $template)
 490     );
 491
 492   } elsif ( grep /\S/,
 493             $conf->config_orbase('invoice_latexreturnaddress', $template) ) {
 494
 495     my $convert_map = $convert_maps{$format}{'returnaddress'};
 496     $returnaddress =
 497       join( "\n",
 498             &$convert_map( $conf->config_orbase( "invoice_latexreturnaddress",
 499                                                  $template
 500                                                )
 501                          )
 502           );
 503   } elsif ( grep /\S/, $conf->config('company_address', $cust_main->agentnum) ) {
 504
 505     my $convert_map = $convert_maps{$format}{'returnaddress'};
 506     $returnaddress = join( "\n", &$convert_map(
 507                                    map { s/( {2,})/'~' x length($1)/eg;
 508                                          s/$/\\\\\*/;
 509                                          $_
 510                                        }
 511                                      ( $conf->config('company_name', $cust_main->agentnum),
 512                                        $conf->config('company_address', $cust_main->agentnum),
 513                                      )
 514                                  )
 515                      );
 516
 517   } else {
 518
 519     my $warning = "Couldn't find a return address; ".
 520                   "do you need to set the company_address configuration value?";
 521     warn "$warning\n";
 522     $returnaddress = $nbsp;
 523     #$returnaddress = $warning;
 524
 525   }
 526
 527   warn "$me generating invoice data\n"
 528     if $DEBUG > 1;
 529
 530   my $agentnum = $cust_main->agentnum;
 531
 532   my %invoice_data = (
 533
 534     #invoice from info
 535     'company_name'    => scalar( $conf->config('company_name', $agentnum) ),
 536     'company_address' => join("\n", $conf->config('company_address', $agentnum) ). "\n",
 537     'company_phonenum'=> scalar( $conf->config('company_phonenum', $agentnum) ),
 538     'returnaddress'   => $returnaddress,
 539     'agent'           => &$escape_function($cust_main->agent->agent),
 540
 541     #invoice/quotation info
 542     'no_number'       => $params{'no_number'},
 543     'invnum'          => ( $params{'no_number'} ? '' : $self->invnum ),
 544     'quotationnum'    => $self->quotationnum,
 545     'no_date'         => $params{'no_date'},
 546     '_date'           => ( $params{'no_date'} ? '' : $self->_date ),
 547       # workaround for inconsistent behavior in the early plain text
 548       # templates; see RT#28271
 549     'date'            => ( $params{'no_date'}
 550                              ? ''
 551                              : ($format eq 'template'
 552                                ? $self->_date
 553                                : $self->time2str_local('long', $self->_date, $format)
 554                                )
 555                          ),
 556     'today'           => $self->time2str_local('long', $today, $format),
 557     'terms'           => $self->terms,
 558     'template'        => $template, #params{'template'},
 559     'notice_name'     => $notice_name, # escape?
 560     'current_charges' => sprintf("%.2f", $self->charged),
 561     'duedate'         => $self->due_date2str('rdate'), #date_format?
 562
 563     #customer info
 564     'custnum'         => $cust_main->display_custnum,
 565     'prospectnum'     => $cust_main->prospectnum,
 566     'agent_custid'    => &$escape_function($cust_main->agent_custid),
 567     ( map { $_ => &$escape_function($cust_main->$_()) } qw(
 568       payname company address1 address2 city state zip fax
 569     )),
 570
 571     #global config
 572     'ship_enable'     => $conf->exists('invoice-ship_address'),
 573     'unitprices'      => $conf->exists('invoice-unitprice'),
 574     'smallernotes'    => $conf->exists('invoice-smallernotes'),
 575     'smallerfooter'   => $conf->exists('invoice-smallerfooter'),
 576     'balance_due_below_line' => $conf->exists('balance_due_below_line'),
 577
 578     #layout info -- would be fancy to calc some of this and bury the template
 579     #               here in the code
 580     'topmargin'             => scalar($conf->config('invoice_latextopmargin', $agentnum)),
 581     'headsep'               => scalar($conf->config('invoice_latexheadsep', $agentnum)),
 582     'textheight'            => scalar($conf->config('invoice_latextextheight', $agentnum)),
 583     'extracouponspace'      => scalar($conf->config('invoice_latexextracouponspace', $agentnum)),
 584     'couponfootsep'         => scalar($conf->config('invoice_latexcouponfootsep', $agentnum)),
 585     'verticalreturnaddress' => $conf->exists('invoice_latexverticalreturnaddress', $agentnum),
 586     'addresssep'            => scalar($conf->config('invoice_latexaddresssep', $agentnum)),
 587     'amountenclosedsep'     => scalar($conf->config('invoice_latexcouponamountenclosedsep', $agentnum)),
 588     'coupontoaddresssep'    => scalar($conf->config('invoice_latexcoupontoaddresssep', $agentnum)),
 589     'addcompanytoaddress'   => $conf->exists('invoice_latexcouponaddcompanytoaddress', $agentnum),
 590
 591     # better hang on to conf_dir for a while (for old templates)
 592     'conf_dir'        => "$FS::UID::conf_dir/conf.$FS::UID::datasrc",
 593
 594     #these are only used when doing paged plaintext
 595     'page'            => 1,
 596     'total_pages'     => 1,
 597
 598   );
 599
 600   #localization
 601   $invoice_data{'emt'} = sub { &$escape_function($self->mt(@_)) };
 602   # prototype here to silence warnings
 603   $invoice_data{'time2str'} = sub ($;$$) { $self->time2str_local(@_, $format) };
 604
 605   my $min_sdate = 999999999999;
 606   my $max_edate = 0;
 607   foreach my $cust_bill_pkg ( $self->cust_bill_pkg ) {
 608     next unless $cust_bill_pkg->pkgnum > 0;
 609     $min_sdate = $cust_bill_pkg->sdate
 610       if length($cust_bill_pkg->sdate) && $cust_bill_pkg->sdate < $min_sdate;
 611     $max_edate = $cust_bill_pkg->edate
 612       if length($cust_bill_pkg->edate) && $cust_bill_pkg->edate > $max_edate;
 613   }
 614
 615   $invoice_data{'bill_period'} = '';
 616   $invoice_data{'bill_period'} =
 617       $self->time2str_local('%e %h', $min_sdate, $format)
 618       . " to " .
 619       $self->time2str_local('%e %h', $max_edate, $format)
 620     if ($max_edate != 0 && $min_sdate != 999999999999);
 621
 622   $invoice_data{finance_section} = '';
 623   if ( $conf->config('finance_pkgclass') ) {
 624     my $pkg_class =
 625       qsearchs('pkg_class', { classnum => $conf->config('finance_pkgclass') });
 626     $invoice_data{finance_section} = $pkg_class->categoryname;
 627   }
 628   $invoice_data{finance_amount} = '0.00';
 629   $invoice_data{finance_section} ||= 'Finance Charges'; #avoid config confusion
 630
 631   my $countrydefault = $conf->config('countrydefault') || 'US';
 632   foreach ( qw( address1 address2 city state zip country fax) ){
 633     my $method = 'ship_'.$_;
 634     $invoice_data{"ship_$_"} = $escape_function->($cust_main->$method);
 635   }
 636   if ( length($cust_main->ship_company) ) {
 637     $invoice_data{'ship_company'} = $escape_function->($cust_main->ship_company);
 638   } else {
 639     $invoice_data{'ship_company'} = $escape_function->($cust_main->company);
 640   }
 641   $invoice_data{'ship_contact'} = $escape_function->($cust_main->contact);
 642   $invoice_data{'ship_country'} = ''
 643     if ( $invoice_data{'ship_country'} eq $countrydefault );
 644
 645   $invoice_data{'cid'} = $params{'cid'}
 646     if $params{'cid'};
 647
 648   if ( $cust_main->country eq $countrydefault ) {
 649     $invoice_data{'country'} = '';
 650   } else {
 651     $invoice_data{'country'} = &$escape_function(code2country($cust_main->country));
 652   }
 653
 654   my @address = ();
 655   $invoice_data{'address'} = \@address;
 656   push @address,
 657     $cust_main->payname.
 658       ( ( $cust_main->payby eq 'BILL' ) && $cust_main->payinfo
 659         ? " (P.O. #". $cust_main->payinfo. ")"
 660         : ''
 661       )
 662   ;
 663   push @address, $cust_main->company
 664     if $cust_main->company;
 665   push @address, $cust_main->address1;
 666   push @address, $cust_main->address2
 667     if $cust_main->address2;
 668   push @address,
 669     $cust_main->city. ", ". $cust_main->state. "  ".  $cust_main->zip;
 670   push @address, $invoice_data{'country'}
 671     if $invoice_data{'country'};
 672   push @address, ''
 673     while (scalar(@address) < 5);
 674
 675   $invoice_data{'logo_file'} = $params{'logo_file'}
 676     if $params{'logo_file'};
 677   $invoice_data{'barcode_file'} = $params{'barcode_file'}
 678     if $params{'barcode_file'};
 679   $invoice_data{'barcode_img'} = $params{'barcode_img'}
 680     if $params{'barcode_img'};
 681   $invoice_data{'barcode_cid'} = $params{'barcode_cid'}
 682     if $params{'barcode_cid'};
 683
 684   my( $pr_total, @pr_cust_bill ) = $self->previous; #previous balance
 685 #  my( $cr_total, @cr_cust_credit ) = $self->cust_credit; #credits
 686   #my $balance_due = $self->owed + $pr_total - $cr_total;
 687   my $balance_due = $self->owed + $pr_total;
 688
 689   # the sum of amount owed on all invoices
 690   # (this is used in the summary & on the payment coupon)
 691   $invoice_data{'balance'} = sprintf("%.2f", $balance_due);
 692
 693   # info from customer's last invoice before this one, for some
 694   # summary formats
 695   $invoice_data{'last_bill'} = {};
 696
 697   if ( $self->custnum && $self->invnum ) {
 698
 699     my $last_bill = $self->previous_bill;
 700     if ( $last_bill ) {
 701
 702       # "balance_date_range" unfortunately is unsuitable for this, since it
 703       # cares about application dates.  We want to know the sum of all
 704       # _top-level transactions_ dated before the last invoice.
 705       my @sql = (
 706         'SELECT SUM(charged) FROM cust_bill WHERE _date <= ? AND custnum = ?',
 707         'SELECT -1*SUM(amount) FROM cust_credit WHERE _date <= ? AND custnum = ?',
 708         'SELECT -1*SUM(paid) FROM cust_pay  WHERE _date <= ? AND custnum = ?',
 709         'SELECT SUM(refund) FROM cust_refund WHERE _date <= ? AND custnum = ?',
 710       );
 711
 712       # the customer's current balance immediately after generating the last
 713       # bill
 714
 715       my $last_bill_balance = $last_bill->charged;
 716       foreach (@sql) {
 717         #warn "$_\n";
 718         my $delta = FS::Record->scalar_sql(
 719           $_,
 720           $last_bill->_date - 1,
 721           $self->custnum,
 722         );
 723         #warn "$delta\n";
 724         $last_bill_balance += $delta;
 725       }
 726
 727       $last_bill_balance = sprintf("%.2f", $last_bill_balance);
 728
 729       warn sprintf("LAST BILL: INVNUM %d, DATE %s, BALANCE %.2f\n\n",
 730         $last_bill->invnum,
 731         $self->time2str_local('%D', $last_bill->_date),
 732         $last_bill_balance
 733       ) if $DEBUG > 0;
 734       # ("true_previous_balance" is a terrible name, but at least it's no
 735       # longer stored in the database)
 736       $invoice_data{'true_previous_balance'} = $last_bill_balance;
 737
 738       # the change in balance from immediately after that invoice
 739       # to immediately before this one
 740       my $before_this_bill_balance = 0;
 741       foreach (@sql) {
 742         #warn "$_\n";
 743         my $delta = FS::Record->scalar_sql(
 744           $_,
 745           $self->_date - 1,
 746           $self->custnum,
 747         );
 748         #warn "$delta\n";
 749         $before_this_bill_balance += $delta;
 750       }
 751       $invoice_data{'balance_adjustments'} =
 752         sprintf("%.2f", $last_bill_balance - $before_this_bill_balance);
 753
 754       warn sprintf("BALANCE ADJUSTMENTS: %.2f\n\n",
 755                    $invoice_data{'balance_adjustments'}
 756       ) if $DEBUG > 0;
 757
 758       # the sum of amount owed on all previous invoices
 759       # ($pr_total is used elsewhere but not as $previous_balance)
 760       $invoice_data{'previous_balance'} = sprintf("%.2f", $pr_total);
 761
 762       $invoice_data{'last_bill'} = {
 763         '_date'     => $last_bill->_date, #unformatted
 764       };
 765       my (@payments, @credits);
 766       # for formats that itemize previous payments
 767       foreach my $cust_pay ( qsearch('cust_pay', {
 768                               'custnum' => $self->custnum,
 769                               '_date'   => { op => '>=',
 770                                              value => $last_bill->_date }
 771                              } ) )
 772       {
 773         next if $cust_pay->_date > $self->_date;
 774         push @payments, {
 775             '_date'       => $cust_pay->_date,
 776             'date'        => $self->time2str_local('long', $cust_pay->_date, $format),
 777             'payinfo'     => $cust_pay->payby_payinfo_pretty,
 778             'amount'      => sprintf('%.2f', $cust_pay->paid),
 779         };
 780         # not concerned about applications
 781       }
 782       foreach my $cust_credit ( qsearch('cust_credit', {
 783                               'custnum' => $self->custnum,
 784                               '_date'   => { op => '>=',
 785                                              value => $last_bill->_date }
 786                              } ) )
 787       {
 788         next if $cust_credit->_date > $self->_date;
 789         push @credits, {
 790             '_date'       => $cust_credit->_date,
 791             'date'        => $self->time2str_local('long', $cust_credit->_date, $format),
 792             'creditreason'=> $cust_credit->reason,
 793             'amount'      => sprintf('%.2f', $cust_credit->amount),
 794         };
 795       }
 796       $invoice_data{'previous_payments'} = \@payments;
 797       $invoice_data{'previous_credits'}  = \@credits;
 798     } else {
 799       # there is no $last_bill
 800       $invoice_data{'true_previous_balance'} =
 801       $invoice_data{'balance_adjustments'}   =
 802       $invoice_data{'previous_balance'}      = '0.00';
 803       $invoice_data{'previous_payments'} = [];
 804       $invoice_data{'previous_credits'} = [];
 805     }
 806   } # if this is an invoice
 807
 808   my $summarypage = '';
 809   if ( $conf->exists('invoice_usesummary', $agentnum) ) {
 810     $summarypage = 1;
 811   }
 812   $invoice_data{'summarypage'} = $summarypage;
 813
 814   warn "$me substituting variables in notes, footer, smallfooter\n"
 815     if $DEBUG > 1;
 816
 817   my $tc = $self->template_conf;
 818   my @include = ( [ $tc,        'notes' ],
 819                   [ 'invoice_', 'footer' ],
 820                   [ 'invoice_', 'smallfooter', ],
 821                 );
 822   push @include, [ $tc,        'coupon', ]
 823     unless $params{'no_coupon'};
 824
 825   foreach my $i (@include) {
 826
 827     my($base, $include) = @$i;
 828
 829     my $inc_file = $conf->key_orbase("$base$format$include", $template);
 830     my @inc_src;
 831
 832     if ( $conf->exists($inc_file, $agentnum)
 833          && length( $conf->config($inc_file, $agentnum) ) ) {
 834
 835       @inc_src = $conf->config($inc_file, $agentnum);
 836
 837     } else {
 838
 839       $inc_file = $conf->key_orbase("${base}latex$include", $template);
 840
 841       my $convert_map = $convert_maps{$format}{$include};
 842
 843       @inc_src = map { s/\[\@--/$delimiters{$format}[0]/g;
 844                        s/--\@\]/$delimiters{$format}[1]/g;
 845                        $_;
 846                      }
 847                  &$convert_map( $conf->config($inc_file, $agentnum) );
 848
 849     }
 850
 851     my $inc_tt = new Text::Template (
 852       TYPE       => 'ARRAY',
 853       SOURCE     => [ map "$_\n", @inc_src ],
 854       DELIMITERS => $delimiters{$format},
 855     ) or die "Can't create new Text::Template object: $Text::Template::ERROR";
 856
 857     unless ( $inc_tt->compile() ) {
 858       my $error = "Can't compile $inc_file template: $Text::Template::ERROR\n";
 859       warn $error. "Template:\n". join('', map "$_\n", @inc_src);
 860       die $error;
 861     }
 862
 863     $invoice_data{$include} = $inc_tt->fill_in( HASH => \%invoice_data );
 864
 865     $invoice_data{$include} =~ s/\n+$//
 866       if ($format eq 'latex');
 867   }
 868
 869   # let invoices use either of these as needed
 870   $invoice_data{'po_num'} = ($cust_main->payby eq 'BILL')
 871     ? $cust_main->payinfo : '';
 872   $invoice_data{'po_line'} =
 873     (  $cust_main->payby eq 'BILL' && $cust_main->payinfo )
 874       ? &$escape_function($self->mt("Purchase Order #").$cust_main->payinfo)
 875       : $nbsp;
 876
 877   my %money_chars = ( 'latex'    => '',
 878                       'html'     => $conf->config('money_char') || '$',
 879                       'template' => '',
 880                     );
 881   my $money_char = $money_chars{$format};
 882
 883   # extremely dubious
 884   my %other_money_chars = ( 'latex'    => '\dollar ',#XXX should be a config too
 885                             'html'     => $conf->config('money_char') || '$',
 886                             'template' => '',
 887                           );
 888   my $other_money_char = $other_money_chars{$format};
 889   $invoice_data{'dollar'} = $other_money_char;
 890
 891   my %minus_signs = ( 'latex'    => '$-$',
 892                       'html'     => '&minus;',
 893                       'template' => '- ' );
 894   my $minus = $minus_signs{$format};
 895
 896   my @detail_items = ();
 897   my @total_items = ();
 898   my @buf = ();
 899   my @sections = ();
 900
 901   $invoice_data{'detail_items'} = \@detail_items;
 902   $invoice_data{'total_items'} = \@total_items;
 903   $invoice_data{'buf'} = \@buf;
 904   $invoice_data{'sections'} = \@sections;
 905
 906   warn "$me generating sections\n"
 907     if $DEBUG > 1;
 908
 909   my $taxtotal = 0;
 910   my $tax_section = { 'description' => $self->mt('Taxes, Surcharges, and Fees'),
 911                       'subtotal'    => $taxtotal,   # adjusted below
 912                       'tax_section' => 1,
 913                     };
 914   my $tax_weight = _pkg_category($tax_section->{description})
 915                         ? _pkg_category($tax_section->{description})->weight
 916                         : 0;
 917   $tax_section->{'summarized'} = ''; #why? $summarypage && !$tax_weight ? 'Y' : '';
 918   $tax_section->{'sort_weight'} = $tax_weight;
 919
 920   my $adjusttotal = 0;
 921   my $adjust_section = {
 922     'description'    => $self->mt('Credits, Payments, and Adjustments'),
 923     'adjust_section' => 1,
 924     'subtotal'       => 0,   # adjusted below
 925   };
 926   my $adjust_weight = _pkg_category($adjust_section->{description})
 927                         ? _pkg_category($adjust_section->{description})->weight
 928                         : 0;
 929   $adjust_section->{'summarized'} = ''; #why? $summarypage && !$adjust_weight ? 'Y' : '';
 930   $adjust_section->{'sort_weight'} = $adjust_weight;
 931
 932   my $unsquelched = $params{unsquelch_cdr} || $cust_main->squelch_cdr ne 'Y';
 933   my $multisection = $conf->exists($tc.'sections', $cust_main->agentnum) ||
 934                      $conf->exists($tc.'sections_by_location', $cust_main->agentnum);
 935   $invoice_data{'multisection'} = $multisection;
 936   my $late_sections;
 937   my $extra_sections = [];
 938   my $extra_lines = ();
 939
 940   # default section ('Charges')
 941   my $default_section = { 'description' => '',
 942                           'subtotal'    => '',
 943                           'no_subtotal' => 1,
 944                         };
 945
 946   # Previous Charges section
 947   # subtotal is the first return value from $self->previous
 948   my $previous_section;
 949   # if the invoice has major sections, or if we're summarizing previous
 950   # charges with a single line, or if we've been specifically told to put them
 951   # in a section, create a section for previous charges:
 952   if ( $multisection or
 953        $conf->exists('previous_balance-summary_only') or
 954        $conf->exists('previous_balance-section') ) {
 955
 956     $previous_section =  { 'description' => $self->mt('Previous Charges'),
 957                            'subtotal'    => $other_money_char.
 958                                             sprintf('%.2f', $pr_total),
 959                            'summarized'  => '', #why? $summarypage ? 'Y' : '',
 960                          };
 961     $previous_section->{posttotal} = '0 / 30 / 60 / 90 days overdue '.
 962       join(' / ', map { $cust_main->balance_date_range(@$_) }
 963                   $self->_prior_month30s
 964           )
 965       if $conf->exists('invoice_include_aging');
 966
 967   } else {
 968     # otherwise put them in the main section
 969     $previous_section = $default_section;
 970   }
 971
 972   if ( $multisection ) {
 973     ($extra_sections, $extra_lines) =
 974       $self->_items_extra_usage_sections($escape_function_nonbsp, $format)
 975       if $conf->exists('usage_class_as_a_section', $cust_main->agentnum)
 976       && $self->can('_items_extra_usage_sections');
 977
 978     push @$extra_sections, $adjust_section if $adjust_section->{sort_weight};
 979
 980     push @detail_items, @$extra_lines if $extra_lines;
 981
 982     # the code is written so that both methods can be used together, but
 983     # we haven't yet changed the template to take advantage of that, so for
 984     # now, treat them as mutually exclusive.
 985     my %section_method = ( by_category => 1 );
 986     if ( $conf->config($tc.'sections_method') eq 'location' ) {
 987       %section_method = ( by_location => 1 );
 988     }
 989     my ($early, $late) =
 990       $self->_items_sections( 'summary' => $summarypage,
 991                               'escape'  => $escape_function_nonbsp,
 992                               'extra_sections' => $extra_sections,
 993                               'format'  => $format,
 994                               %section_method
 995                             );
 996     push @sections, @$early;
 997     $late_sections = $late;
 998
 999     if (    $conf->exists('svc_phone_sections')
1000          && $self->can('_items_svc_phone_sections')
1001        )
1002     {
1003       my ($phone_sections, $phone_lines) =
1004         $self->_items_svc_phone_sections($escape_function_nonbsp, $format);
1005       push @{$late_sections}, @$phone_sections;
1006       push @detail_items, @$phone_lines;
1007     }
1008     if ( $conf->exists('voip-cust_accountcode_cdr')
1009          && $cust_main->accountcode_cdr
1010          && $self->can('_items_accountcode_cdr')
1011        )
1012     {
1013       my ($accountcode_section, $accountcode_lines) =
1014         $self->_items_accountcode_cdr($escape_function_nonbsp,$format);
1015       if ( scalar(@$accountcode_lines) ) {
1016           push @{$late_sections}, $accountcode_section;
1017           push @detail_items, @$accountcode_lines;
1018       }
1019     }
1020   } else {# not multisection
1021     # make a default section
1022     push @sections, $default_section;
1023     # and calculate the finance charge total, since it won't get done otherwise.
1024     # and the default section total
1025     # XXX possibly finance_pkgclass should not be used in this manner?
1026     my @finance_charges;
1027     my @charges;
1028     foreach my $cust_bill_pkg ( $self->cust_bill_pkg ) {
1029       if ( $invoice_data{finance_section} and
1030         grep { $_->section eq $invoice_data{finance_section} }
1031            $cust_bill_pkg->cust_bill_pkg_display ) {
1032         # I think these are always setup fees, but just to be sure...
1033         push @finance_charges, $cust_bill_pkg->recur + $cust_bill_pkg->setup;
1034       } else {
1035         push @charges, $cust_bill_pkg->recur + $cust_bill_pkg->setup;
1036       }
1037     }
1038     $invoice_data{finance_amount} =
1039       sprintf('%.2f', sum( @finance_charges ) || 0);
1040     $default_section->{subtotal} = $other_money_char.
1041                                     sprintf('%.2f', sum( @charges ) || 0);
1042   }
1043
1044   # start setting up summary subtotals
1045   my @summary_subtotals;
1046   my $method = $conf->config('summary_subtotals_method');
1047   if ( $method and $method ne $conf->config($tc.'sections_method') ) {
1048     # then re-section them by the correct method
1049     my %section_method = ( by_category => 1 );
1050     if ( $conf->config('summary_subtotals_method') eq 'location' ) {
1051       %section_method = ( by_location => 1 );
1052     }
1053     my ($early, $late) =
1054       $self->_items_sections( 'summary' => $summarypage,
1055                               'escape'  => $escape_function_nonbsp,
1056                               'extra_sections' => $extra_sections,
1057                               'format'  => $format,
1058                               %section_method
1059                             );
1060     foreach ( @$early ) {
1061       next if $_->{subtotal} == 0;
1062       $_->{subtotal} = $other_money_char.sprintf('%.2f', $_->{subtotal});
1063       push @summary_subtotals, $_;
1064     }
1065   } else {
1066     # subtotal sectioning is the same as for the actual invoice sections
1067     @summary_subtotals = @sections;
1068   }
1069
1070   # Hereafter, push sections to both @sections and @summary_subtotals
1071   # if they belong in both places (e.g. tax section).  Late sections are
1072   # never in @summary_subtotals.
1073
1074   # previous invoice balances in the Previous Charges section if there
1075   # is one, otherwise in the main detail section
1076   # (except if summary_only is enabled, don't show them at all)
1077   if ( $self->can('_items_previous') &&
1078        $self->enable_previous &&
1079        ! $conf->exists('previous_balance-summary_only') ) {
1080
1081     warn "$me adding previous balances\n"
1082       if $DEBUG > 1;
1083
1084     foreach my $line_item ( $self->_items_previous ) {
1085
1086       my $detail = {
1087         ref             => $line_item->{'pkgnum'},
1088         pkgpart         => $line_item->{'pkgpart'},
1089         #quantity        => 1, # not really correct
1090         section         => $previous_section, # which might be $default_section
1091         description     => &$escape_function($line_item->{'description'}),
1092         ext_description => [ map { &$escape_function($_) }
1093                              @{ $line_item->{'ext_description'} || [] }
1094                            ],
1095         amount          => $money_char . $line_item->{'amount'},
1096         product_code    => $line_item->{'pkgpart'} || 'N/A',
1097       };
1098
1099       push @detail_items, $detail;
1100       push @buf, [ $detail->{'description'},
1101                    $money_char. sprintf("%10.2f", $line_item->{'amount'}),
1102                  ];
1103     }
1104
1105   }
1106
1107   if ( @pr_cust_bill && $self->enable_previous ) {
1108     push @buf, ['','-----------'];
1109     push @buf, [ $self->mt('Total Previous Balance'),
1110                  $money_char. sprintf("%10.2f", $pr_total) ];
1111     push @buf, ['',''];
1112   }
1113
1114   if ( $conf->exists('svc_phone-did-summary') && $self->can('_did_summary') ) {
1115       warn "$me adding DID summary\n"
1116         if $DEBUG > 1;
1117
1118       my ($didsummary,$minutes) = $self->_did_summary;
1119       my $didsummary_desc = 'DID Activity Summary (since last invoice)';
1120       push @detail_items,
1121        { 'description' => $didsummary_desc,
1122            'ext_description' => [ $didsummary, $minutes ],
1123        };
1124   }
1125
1126   foreach my $section (@sections, @$late_sections) {
1127
1128     # begin some normalization
1129     $section->{'subtotal'} = $section->{'amount'}
1130       if $multisection
1131          && !exists($section->{subtotal})
1132          && exists($section->{amount});
1133
1134     $invoice_data{finance_amount} = sprintf('%.2f', $section->{'subtotal'} )
1135       if ( $invoice_data{finance_section} &&
1136            $section->{'description'} eq $invoice_data{finance_section} );
1137
1138     $section->{'subtotal'} = $other_money_char.
1139                              sprintf('%.2f', $section->{'subtotal'})
1140       if $multisection;
1141
1142     # continue some normalization
1143     $section->{'amount'}   = $section->{'subtotal'}
1144       if $multisection;
1145
1146
1147     if ( $section->{'description'} ) {
1148       push @buf, ( [ &$escape_function($section->{'description'}), '' ],
1149                    [ '', '' ],
1150                  );
1151     }
1152
1153     warn "$me   setting options\n"
1154       if $DEBUG > 1;
1155
1156     my %options = ();
1157     $options{'section'} = $section if $multisection;
1158     $options{'format'} = $format;
1159     $options{'escape_function'} = $escape_function;
1160     $options{'no_usage'} = 1 unless $unsquelched;
1161     $options{'unsquelched'} = $unsquelched;
1162     $options{'summary_page'} = $summarypage;
1163     $options{'skip_usage'} =
1164       scalar(@$extra_sections) && !grep{$section == $_} @$extra_sections;
1165     $options{'preref_callback'} = $params{'preref_callback'};
1166
1167     warn "$me   searching for line items\n"
1168       if $DEBUG > 1;
1169
1170     foreach my $line_item ( $self->_items_pkg(%options),
1171                             $self->_items_fee(%options) ) {
1172
1173       warn "$me     adding line item ".
1174            join(', ', map "$_=>".$line_item->{$_}, keys %$line_item). "\n"
1175         if $DEBUG > 1;
1176
1177       $line_item->{'ref'} = $line_item->{'pkgnum'};
1178       $line_item->{'product_code'} = $line_item->{'pkgpart'} || 'N/A'; # mt()?
1179       $line_item->{'section'} = $section;
1180       $line_item->{'description'} = &$escape_function($line_item->{'description'});
1181       $line_item->{'amount'} = $money_char.$line_item->{'amount'};
1182
1183       if ( length($line_item->{'unit_amount'}) ) {
1184         $line_item->{'unit_amount'} = $money_char.$line_item->{'unit_amount'};
1185       }
1186       $line_item->{'ext_description'} ||= [];
1187
1188       push @detail_items, $line_item;
1189       push @buf, ( [ $line_item->{'description'},
1190                      $money_char. sprintf("%10.2f", $line_item->{'amount'}),
1191                    ],
1192                    map { [ " ". $_, '' ] } @{$line_item->{'ext_description'}},
1193                  );
1194     }
1195
1196     if ( $section->{'description'} ) {
1197       push @buf, ( ['','-----------'],
1198                    [ $section->{'description'}. ' sub-total',
1199                       $section->{'subtotal'} # already formatted this
1200                    ],
1201                    [ '', '' ],
1202                    [ '', '' ],
1203                  );
1204     }
1205
1206   }
1207
1208   $invoice_data{current_less_finance} =
1209     sprintf('%.2f', $self->charged - $invoice_data{finance_amount} );
1210
1211   # if there's anything in the Previous Charges section, prepend it to the list
1212   if ( $pr_total and $previous_section ne $default_section ) {
1213     unshift @sections, $previous_section;
1214     # but not @summary_subtotals
1215   }
1216
1217   warn "$me adding taxes\n"
1218     if $DEBUG > 1;
1219
1220   my @items_tax = $self->_items_tax;
1221   foreach my $tax ( @items_tax ) {
1222
1223     $taxtotal += $tax->{'amount'};
1224
1225     my $description = &$escape_function( $tax->{'description'} );
1226     my $amount      = sprintf( '%.2f', $tax->{'amount'} );
1227
1228     if ( $multisection ) {
1229
1230       push @detail_items, {
1231         ext_description => [],
1232         ref          => '',
1233         quantity     => '',
1234         description  => $description,
1235         amount       => $money_char. $amount,
1236         product_code => '',
1237         section      => $tax_section,
1238       };
1239
1240     } else {
1241
1242       push @total_items, {
1243         'total_item'   => $description,
1244         'total_amount' => $other_money_char. $amount,
1245       };
1246
1247     }
1248
1249     push @buf,[ $description,
1250                 $money_char. $amount,
1251               ];
1252
1253   }
1254
1255   if ( @items_tax ) {
1256     my $total = {};
1257     $total->{'total_item'} = $self->mt('Sub-total');
1258     $total->{'total_amount'} =
1259       $other_money_char. sprintf('%.2f', $self->charged - $taxtotal );
1260
1261     if ( $multisection ) {
1262       $tax_section->{'subtotal'} = $other_money_char.
1263                                    sprintf('%.2f', $taxtotal);
1264       $tax_section->{'pretotal'} = 'New charges sub-total '.
1265                                    $total->{'total_amount'};
1266       if ( $taxtotal ) {
1267         push @sections, $tax_section;
1268         push @summary_subtotals, $tax_section;
1269       }
1270     } else {
1271       unshift @total_items, $total;
1272     }
1273   }
1274   $invoice_data{'taxtotal'} = sprintf('%.2f', $taxtotal);
1275
1276   push @buf,['','-----------'];
1277   push @buf,[$self->mt(
1278               (!$self->enable_previous)
1279                ? 'Total Charges'
1280                : 'Total New Charges'
1281              ),
1282              $money_char. sprintf("%10.2f",$self->charged) ];
1283   push @buf,['',''];
1284
1285
1286   ###
1287   # Totals
1288   ###
1289
1290   my %embolden_functions = (
1291     'latex'    => sub { return '\textbf{'. shift(). '}' },
1292     'html'     => sub { return '<b>'. shift(). '</b>' },
1293     'template' => sub { shift },
1294   );
1295   my $embolden_function = $embolden_functions{$format};
1296
1297   if ( $self->can('_items_total') ) { # quotations
1298
1299     $self->_items_total(\@total_items);
1300
1301     foreach ( @total_items ) {
1302       $_->{'total_item'}   = &$embolden_function( $_->{'total_item'} );
1303       $_->{'total_amount'} = &$embolden_function( $other_money_char.
1304                                                    $_->{'total_amount'}
1305                                                 );
1306     }
1307
1308   } else { #normal invoice case
1309
1310     # calculate total, possibly including total owed on previous
1311     # invoices
1312     my $total = {};
1313     my $item = 'Total';
1314     $item = $conf->config('previous_balance-exclude_from_total')
1315          || 'Total New Charges'
1316       if $conf->exists('previous_balance-exclude_from_total');
1317     my $amount = $self->charged;
1318     if ( $self->enable_previous and !$conf->exists('previous_balance-exclude_from_total') ) {
1319       $amount += $pr_total;
1320     }
1321
1322     $total->{'total_item'} = &$embolden_function($self->mt($item));
1323     $total->{'total_amount'} =
1324       &$embolden_function( $other_money_char.  sprintf( '%.2f', $amount ) );
1325     if ( $multisection ) {
1326       if ( $adjust_section->{'sort_weight'} ) {
1327         $adjust_section->{'posttotal'} = $self->mt('Balance Forward').' '.
1328           $other_money_char.  sprintf("%.2f", ($self->billing_balance || 0) );
1329       } else {
1330         $adjust_section->{'pretotal'} = $self->mt('New charges total').' '.
1331           $other_money_char.  sprintf('%.2f', $self->charged );
1332       }
1333     } else {
1334       push @total_items, $total;
1335     }
1336     push @buf,['','-----------'];
1337     push @buf,[$item,
1338                $money_char.
1339                sprintf( '%10.2f', $amount )
1340               ];
1341     push @buf,['',''];
1342
1343     # if we're showing previous invoices, also show previous
1344     # credits and payments
1345     if ( $self->enable_previous
1346           and $self->can('_items_credits')
1347           and $self->can('_items_payments') )
1348       {
1349       #foreach my $thing ( sort { $a->_date <=> $b->_date } $self->_items_credits, $self->_items_payments
1350
1351       # credits
1352       my $credittotal = 0;
1353       foreach my $credit (
1354         $self->_items_credits( 'template' => $template, 'trim_len' => 60 )
1355       ) {
1356
1357         my $total;
1358         $total->{'total_item'} = &$escape_function($credit->{'description'});
1359         $credittotal += $credit->{'amount'};
1360         $total->{'total_amount'} = $minus.$other_money_char.$credit->{'amount'};
1361         $adjusttotal += $credit->{'amount'};
1362         if ( $multisection ) {
1363           push @detail_items, {
1364             ext_description => [],
1365             ref          => '',
1366             quantity     => '',
1367             description  => &$escape_function($credit->{'description'}),
1368             amount       => $money_char . $credit->{'amount'},
1369             product_code => '',
1370             section      => $adjust_section,
1371           };
1372         } else {
1373           push @total_items, $total;
1374         }
1375
1376       }
1377       $invoice_data{'credittotal'} = sprintf('%.2f', $credittotal);
1378
1379       #credits (again)
1380       foreach my $credit (
1381         $self->_items_credits( 'template' => $template, 'trim_len'=>32 )
1382       ) {
1383         push @buf, [ $credit->{'description'}, $money_char.$credit->{'amount'} ];
1384       }
1385
1386       # payments
1387       my $paymenttotal = 0;
1388       foreach my $payment (
1389         $self->_items_payments( 'template' => $template )
1390       ) {
1391         my $total = {};
1392         $total->{'total_item'} = &$escape_function($payment->{'description'});
1393         $paymenttotal += $payment->{'amount'};
1394         $total->{'total_amount'} = $minus.$other_money_char.$payment->{'amount'};
1395         $adjusttotal += $payment->{'amount'};
1396         if ( $multisection ) {
1397           push @detail_items, {
1398             ext_description => [],
1399             ref          => '',
1400             quantity     => '',
1401             description  => &$escape_function($payment->{'description'}),
1402             amount       => $money_char . $payment->{'amount'},
1403             product_code => '',
1404             section      => $adjust_section,
1405           };
1406         }else{
1407           push @total_items, $total;
1408         }
1409         push @buf, [ $payment->{'description'},
1410                      $money_char. sprintf("%10.2f", $payment->{'amount'}),
1411                    ];
1412       }
1413       $invoice_data{'paymenttotal'} = sprintf('%.2f', $paymenttotal);
1414
1415       if ( $multisection ) {
1416         $adjust_section->{'subtotal'} = $other_money_char.
1417                                         sprintf('%.2f', $adjusttotal);
1418         push @sections, $adjust_section
1419           unless $adjust_section->{sort_weight};
1420         # do not summarize; adjustments there are shown according to
1421         # different rules
1422       }
1423
1424       # create Balance Due message
1425       {
1426         my $total;
1427         $total->{'total_item'} = &$embolden_function($self->balance_due_msg);
1428         $total->{'total_amount'} =
1429           &$embolden_function(
1430             $other_money_char. sprintf('%.2f', #why? $summarypage
1431                                                #  ? $self->charged +
1432                                                #    $self->billing_balance
1433                                                #  :
1434                                                    $self->owed + $pr_total
1435                                       )
1436           );
1437         if ( $multisection && !$adjust_section->{sort_weight} ) {
1438           $adjust_section->{'posttotal'} = $total->{'total_item'}. ' '.
1439                                            $total->{'total_amount'};
1440         }else{
1441           push @total_items, $total;
1442         }
1443         push @buf,['','-----------'];
1444         push @buf,[$self->balance_due_msg, $money_char.
1445           sprintf("%10.2f", $balance_due ) ];
1446       }
1447
1448       if ( $conf->exists('previous_balance-show_credit')
1449           and $cust_main->balance < 0 ) {
1450         my $credit_total = {
1451           'total_item'    => &$embolden_function($self->credit_balance_msg),
1452           'total_amount'  => &$embolden_function(
1453             $other_money_char. sprintf('%.2f', -$cust_main->balance)
1454           ),
1455         };
1456         if ( $multisection ) {
1457           $adjust_section->{'posttotal'} .= $newline_token .
1458             $credit_total->{'total_item'} . ' ' . $credit_total->{'total_amount'};
1459         }
1460         else {
1461           push @total_items, $credit_total;
1462         }
1463         push @buf,['','-----------'];
1464         push @buf,[$self->credit_balance_msg, $money_char.
1465           sprintf("%10.2f", -$cust_main->balance ) ];
1466       }
1467     }
1468
1469   } #end of default total adding ! can('_items_total')
1470
1471   if ( $multisection ) {
1472     if (    $conf->exists('svc_phone_sections')
1473          && $self->can('_items_svc_phone_sections')
1474        )
1475     {
1476       my $total;
1477       $total->{'total_item'} = &$embolden_function($self->balance_due_msg);
1478       $total->{'total_amount'} =
1479         &$embolden_function(
1480           $other_money_char. sprintf('%.2f', $self->owed + $pr_total)
1481         );
1482       my $last_section = pop @sections;
1483       $last_section->{'posttotal'} = $total->{'total_item'}. ' '.
1484                                      $total->{'total_amount'};
1485       push @sections, $last_section;
1486     }
1487     push @sections, @$late_sections
1488       if $unsquelched;
1489   }
1490
1491   # make a discounts-available section, even without multisection
1492   if ( $conf->exists('discount-show_available')
1493        and my @discounts_avail = $self->_items_discounts_avail ) {
1494     my $discount_section = {
1495       'description' => $self->mt('Discounts Available'),
1496       'subtotal'    => '',
1497       'no_subtotal' => 1,
1498     };
1499
1500     push @sections, $discount_section; # do not summarize
1501     push @detail_items, map { +{
1502         'ref'         => '', #should this be something else?
1503         'section'     => $discount_section,
1504         'description' => &$escape_function( $_->{description} ),
1505         'amount'      => $money_char . &$escape_function( $_->{amount} ),
1506         'ext_description' => [ &$escape_function($_->{ext_description}) || () ],
1507     } } @discounts_avail;
1508   }
1509
1510   # not adding any more sections after this
1511   $invoice_data{summary_subtotals} = \@summary_subtotals;
1512
1513   # usage subtotals
1514   if ( $conf->exists('usage_class_summary')
1515        and $self->can('_items_usage_class_summary') ) {
1516     my @usage_subtotals = $self->_items_usage_class_summary(escape => $escape_function);
1517     if ( @usage_subtotals ) {
1518       unshift @sections, $usage_subtotals[0]->{section}; # do not summarize
1519       unshift @detail_items, @usage_subtotals;
1520     }
1521   }
1522
1523   # invoice history "section" (not really a section)
1524   # not to be included in any subtotals, completely independent of
1525   # everything...
1526   if ( $conf->exists('previous_invoice_history') ) {
1527     my %history;
1528     my %monthorder;
1529     foreach my $cust_bill ( $cust_main->cust_bill ) {
1530       # XXX hardcoded format, and currently only 'charged'; add other fields
1531       # if they become necessary
1532       my $date = $self->time2str_local('%b %Y', $cust_bill->_date);
1533       $history{$date} ||= 0;
1534       $history{$date} += $cust_bill->charged;
1535       # just so we have a numeric sort key
1536       $monthorder{$date} ||= $cust_bill->_date;
1537     }
1538     my @sorted_months = sort { $monthorder{$a} <=> $monthorder{$b} }
1539                         keys %history;
1540     my @sorted_amounts = map { sprintf('%.2f', $history{$_}) } @sorted_months;
1541     $invoice_data{monthly_history} = [ \@sorted_months, \@sorted_amounts ];
1542   }
1543
1544   # service locations: another option for template customization
1545   my %location_info;
1546   foreach my $item (@detail_items) {
1547     if ( $item->{locationnum} ) {
1548       $location_info{ $item->{locationnum} } ||= {
1549         FS::cust_location->by_key( $item->{locationnum} )->location_hash
1550       };
1551     }
1552   }
1553   $invoice_data{location_info} = \%location_info;
1554
1555   # debugging hook: call this with 'diag' => 1 to just get a hash of
1556   # the invoice variables
1557   return \%invoice_data if ( $params{'diag'} );
1558
1559   # All sections and items are built; now fill in templates.
1560   my @includelist = ();
1561   push @includelist, 'summary' if $summarypage;
1562   foreach my $include ( @includelist ) {
1563
1564     my $inc_file = $conf->key_orbase("invoice_${format}$include", $template);
1565     my @inc_src;
1566
1567     if ( length( $conf->config($inc_file, $agentnum) ) ) {
1568
1569       @inc_src = $conf->config($inc_file, $agentnum);
1570
1571     } else {
1572
1573       $inc_file = $conf->key_orbase("invoice_latex$include", $template);
1574
1575       my $convert_map = $convert_maps{$format}{$include};
1576
1577       @inc_src = map { s/\[\@--/$delimiters{$format}[0]/g;
1578                        s/--\@\]/$delimiters{$format}[1]/g;
1579                        $_;
1580                      }
1581                  &$convert_map( $conf->config($inc_file, $agentnum) );
1582
1583     }
1584
1585     my $inc_tt = new Text::Template (
1586       TYPE       => 'ARRAY',
1587       SOURCE     => [ map "$_\n", @inc_src ],
1588       DELIMITERS => $delimiters{$format},
1589     ) or die "Can't create new Text::Template object: $Text::Template::ERROR";
1590
1591     unless ( $inc_tt->compile() ) {
1592       my $error = "Can't compile $inc_file template: $Text::Template::ERROR\n";
1593       warn $error. "Template:\n". join('', map "$_\n", @inc_src);
1594       die $error;
1595     }
1596
1597     $invoice_data{$include} = $inc_tt->fill_in( HASH => \%invoice_data );
1598
1599     $invoice_data{$include} =~ s/\n+$//
1600       if ($format eq 'latex');
1601   }
1602
1603   $invoice_lines = 0;
1604   my $wasfunc = 0;
1605   foreach ( grep /invoice_lines\(\d*\)/, @invoice_template ) { #kludgy
1606     /invoice_lines\((\d*)\)/;
1607     $invoice_lines += $1 || scalar(@buf);
1608     $wasfunc=1;
1609   }
1610   die "no invoice_lines() functions in template?"
1611     if ( $format eq 'template' && !$wasfunc );
1612
1613   if ($format eq 'template') {
1614
1615     if ( $invoice_lines ) {
1616       $invoice_data{'total_pages'} = int( scalar(@buf) / $invoice_lines );
1617       $invoice_data{'total_pages'}++
1618         if scalar(@buf) % $invoice_lines;
1619     }
1620
1621     #setup subroutine for the template
1622     $invoice_data{invoice_lines} = sub {
1623       my $lines = shift || scalar(@buf);
1624       map {
1625         scalar(@buf)
1626           ? shift @buf
1627           : [ '', '' ];
1628       }
1629       ( 1 .. $lines );
1630     };
1631
1632     my $lines;
1633     my @collect;
1634     while (@buf) {
1635       push @collect, split("\n",
1636         $text_template->fill_in( HASH => \%invoice_data )
1637       );
1638       $invoice_data{'page'}++;
1639     }
1640     map "$_\n", @collect;
1641
1642   } else { # this is where we actually create the invoice
1643
1644     warn "filling in template for invoice ". $self->invnum. "\n"
1645       if $DEBUG;
1646     warn join("\n", map " $_ => ". $invoice_data{$_}, keys %invoice_data). "\n"
1647       if $DEBUG > 1;
1648
1649     $text_template->fill_in(HASH => \%invoice_data);
1650   }
1651 }
1652
1653 sub notice_name { '('.shift->table.')'; }
1654
1655 sub template_conf { 'invoice_'; }
1656
1657 # helper routine for generating date ranges
1658 sub _prior_month30s {
1659   my $self = shift;
1660   my @ranges = (
1661    [ 1,       2592000 ], # 0-30 days ago
1662    [ 2592000, 5184000 ], # 30-60 days ago
1663    [ 5184000, 7776000 ], # 60-90 days ago
1664    [ 7776000, 0       ], # 90+   days ago
1665   );
1666
1667   map { [ $_->[0] ? $self->_date - $_->[0] - 1 : '',
1668           $_->[1] ? $self->_date - $_->[1] - 1 : '',
1669       ] }
1670   @ranges;
1671 }
1672
1673 =item print_ps HASHREF | [ TIME [ , TEMPLATE ] ]
1674
1675 Returns an postscript invoice, as a scalar.
1676
1677 Options can be passed as a hashref (recommended) or as a list of time, template
1678 and then any key/value pairs for any other options.
1679
1680 I<time> an optional value used to control the printing of overdue messages.  The
1681 default is now.  It isn't the date of the invoice; that's the `_date' field.
1682 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
1683 L<Time::Local> and L<Date::Parse> for conversion functions.
1684
1685 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
1686
1687 =cut
1688
1689 sub print_ps {
1690   my $self = shift;
1691
1692   my ($file, $logofile, $barcodefile) = $self->print_latex(@_);
1693   my $ps = generate_ps($file);
1694   unlink($logofile);
1695   unlink($barcodefile) if $barcodefile;
1696
1697   $ps;
1698 }
1699
1700 =item print_pdf HASHREF | [ TIME [ , TEMPLATE ] ]
1701
1702 Returns an PDF invoice, as a scalar.
1703
1704 Options can be passed as a hashref (recommended) or as a list of time, template
1705 and then any key/value pairs for any other options.
1706
1707 I<time> an optional value used to control the printing of overdue messages.  The
1708 default is now.  It isn't the date of the invoice; that's the `_date' field.
1709 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
1710 L<Time::Local> and L<Date::Parse> for conversion functions.
1711
1712 I<template>, if specified, is the name of a suffix for alternate invoices.
1713
1714 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
1715
1716 =cut
1717
1718 sub print_pdf {
1719   my $self = shift;
1720
1721   my ($file, $logofile, $barcodefile) = $self->print_latex(@_);
1722   my $pdf = generate_pdf($file);
1723   unlink($logofile);
1724   unlink($barcodefile) if $barcodefile;
1725
1726   $pdf;
1727 }
1728
1729 =item print_html HASHREF | [ TIME [ , TEMPLATE [ , CID ] ] ]
1730
1731 Returns an HTML invoice, as a scalar.
1732
1733 I<time> an optional value used to control the printing of overdue messages.  The
1734 default is now.  It isn't the date of the invoice; that's the `_date' field.
1735 It is specified as a UNIX timestamp; see L<perlfunc/"time">.  Also see
1736 L<Time::Local> and L<Date::Parse> for conversion functions.
1737
1738 I<template>, if specified, is the name of a suffix for alternate invoices.
1739
1740 I<notice_name>, if specified, overrides "Invoice" as the name of the sent document (templates from 10/2009 or newer required)
1741
1742 I<cid> is a MIME Content-ID used to create a "cid:" URL for the logo image, used
1743 when emailing the invoice as part of a multipart/related MIME email.
1744
1745 =cut
1746
1747 sub print_html {
1748   my $self = shift;
1749   my %params;
1750   if ( ref($_[0]) ) {
1751     %params = %{ shift() };
1752   } else {
1753     %params = @_;
1754   }
1755   $params{'format'} = 'html';
1756
1757   $self->print_generic( %params );
1758 }
1759
1760 # quick subroutine for print_latex
1761 #
1762 # There are ten characters that LaTeX treats as special characters, which
1763 # means that they do not simply typeset themselves:
1764 #      # $ % & ~ _ ^ \ { }
1765 #
1766 # TeX ignores blanks following an escaped character; if you want a blank (as
1767 # in "10% of ..."), you have to "escape" the blank as well ("10\%\ of ...").
1768
1769 sub _latex_escape {
1770   my $value = shift;
1771   $value =~ s/([#\$%&~_\^{}])( )?/"\\$1". ( ( defined($2) && length($2) ) ? "\\$2" : '' )/ge;
1772   $value =~ s/([<>])/\$$1\$/g;
1773   $value;
1774 }
1775
1776 sub _html_escape {
1777   my $value = shift;
1778   encode_entities($value);
1779   $value;
1780 }
1781
1782 sub _html_escape_nbsp {
1783   my $value = _html_escape(shift);
1784   $value =~ s/ +/&nbsp;/g;
1785   $value;
1786 }
1787
1788 #utility methods for print_*
1789
1790 sub _translate_old_latex_format {
1791   warn "_translate_old_latex_format called\n"
1792     if $DEBUG;
1793
1794   my @template = ();
1795   while ( @_ ) {
1796     my $line = shift;
1797
1798     if ( $line =~ /^%%Detail\s*$/ ) {
1799
1800       push @template, q![@--!,
1801                       q!  foreach my $_tr_line (@detail_items) {!,
1802                       q!    if ( scalar ($_tr_item->{'ext_description'} ) ) {!,
1803                       q!      $_tr_line->{'description'} .= !,
1804                       q!        "\\tabularnewline\n~~".!,
1805                       q!        join( "\\tabularnewline\n~~",!,
1806                       q!          @{$_tr_line->{'ext_description'}}!,
1807                       q!        );!,
1808                       q!    }!;
1809
1810       while ( ( my $line_item_line = shift )
1811               !~ /^%%EndDetail\s*$/                            ) {
1812         $line_item_line =~ s/'/\\'/g;    # nice LTS
1813         $line_item_line =~ s/\\/\\\\/g;  # escape quotes and backslashes
1814         $line_item_line =~ s/\$(\w+)/'. \$_tr_line->{$1}. '/g;
1815         push @template, "    \$OUT .= '$line_item_line';";
1816       }
1817
1818       push @template, '}',
1819                       '--@]';
1820       #' doh, gvim
1821     } elsif ( $line =~ /^%%TotalDetails\s*$/ ) {
1822
1823       push @template, '[@--',
1824                       '  foreach my $_tr_line (@total_items) {';
1825
1826       while ( ( my $total_item_line = shift )
1827               !~ /^%%EndTotalDetails\s*$/                      ) {
1828         $total_item_line =~ s/'/\\'/g;    # nice LTS
1829         $total_item_line =~ s/\\/\\\\/g;  # escape quotes and backslashes
1830         $total_item_line =~ s/\$(\w+)/'. \$_tr_line->{$1}. '/g;
1831         push @template, "    \$OUT .= '$total_item_line';";
1832       }
1833
1834       push @template, '}',
1835                       '--@]';
1836
1837     } else {
1838       $line =~ s/\$(\w+)/[\@-- \$$1 --\@]/g;
1839       push @template, $line;
1840     }
1841
1842   }
1843
1844   if ($DEBUG) {
1845     warn "$_\n" foreach @template;
1846   }
1847
1848   (@template);
1849 }
1850
1851 sub terms {
1852   my $self = shift;
1853   my $conf = $self->conf;
1854
1855   #check for an invoice-specific override
1856   return $self->invoice_terms if $self->invoice_terms;
1857
1858   #check for a customer- specific override
1859   my $cust_main = $self->cust_main;
1860   return $cust_main->invoice_terms if $cust_main && $cust_main->invoice_terms;
1861
1862   #use configured default
1863   $conf->config('invoice_default_terms') || '';
1864 }
1865
1866 sub due_date {
1867   my $self = shift;
1868   my $duedate = '';
1869   if ( $self->terms =~ /^\s*Net\s*(\d+)\s*$/ ) {
1870     $duedate = $self->_date() + ( $1 * 86400 );
1871   }
1872   $duedate;
1873 }
1874
1875 sub due_date2str {
1876   my $self = shift;
1877   $self->due_date ? $self->time2str_local(shift, $self->due_date) : '';
1878 }
1879
1880 sub balance_due_msg {
1881   my $self = shift;
1882   my $msg = $self->mt('Balance Due');
1883   return $msg unless $self->terms;
1884   if ( $self->due_date ) {
1885     $msg .= ' - ' . $self->mt('Please pay by'). ' '.
1886       $self->due_date2str('short');
1887   } elsif ( $self->terms ) {
1888     $msg .= ' - '. $self->terms;
1889   }
1890   $msg;
1891 }
1892
1893 sub balance_due_date {
1894   my $self = shift;
1895   my $conf = $self->conf;
1896   my $duedate = '';
1897   if (    $conf->exists('invoice_default_terms')
1898        && $conf->config('invoice_default_terms')=~ /^\s*Net\s*(\d+)\s*$/ ) {
1899     $duedate = $self->time2str_local('rdate', $self->_date + ($1*86400) );
1900   }
1901   $duedate;
1902 }
1903
1904 sub credit_balance_msg {
1905   my $self = shift;
1906   $self->mt('Credit Balance Remaining')
1907 }
1908
1909 =item _date_pretty
1910
1911 Returns a string with the date, for example: "3/20/2008", localized for the
1912 customer.  Use _date_pretty_unlocalized for non-end-customer display use.
1913
1914 =cut
1915
1916 sub _date_pretty {
1917   my $self = shift;
1918   $self->time2str_local('short', $self->_date);
1919 }
1920
1921 =item _date_pretty_unlocalized
1922
1923 Returns a string with the date, for example: "3/20/2008", in the format
1924 configured for the back-office.  Use _date_pretty for end-customer display use.
1925
1926 =cut
1927
1928 sub _date_pretty_unlocalized {
1929   my $self = shift;
1930   time2str($date_format, $self->_date);
1931 }
1932
1933 =item _items_sections OPTIONS
1934
1935 Generate section information for all items appearing on this invoice.
1936 This will only be called for multi-section invoices.
1937
1938 For each line item (L<FS::cust_bill_pkg> record), this will fetch all
1939 related display records (L<FS::cust_bill_pkg_display>) and organize
1940 them into two groups ("early" and "late" according to whether they come
1941 before or after the total), then into sections.  A subtotal is calculated
1942 for each section.
1943
1944 Section descriptions are returned in sort weight order.  Each consists
1945 of a hash containing:
1946
1947 description: the package category name, escaped
1948 subtotal: the total charges in that section
1949 tax_section: a flag indicating that the section contains only tax charges
1950 summarized: same as tax_section, for some reason
1951 sort_weight: the package category's sort weight
1952
1953 If 'condense' is set on the display record, it also contains everything
1954 returned from C<_condense_section()>, i.e. C<_condensed_foo_generator>
1955 coderefs to generate parts of the invoice.  This is not advised.
1956
1957 The method returns two arrayrefs, one of "early" sections and one of "late"
1958 sections.
1959
1960 OPTIONS may include:
1961
1962 by_location: a flag to divide the invoice into sections by location.
1963 Each section hash will have a 'location' element containing a hashref of
1964 the location fields (see L<FS::cust_location>).  The section description
1965 will be the location label, but the template can use any of the location
1966 fields to create a suitable label.
1967
1968 by_category: a flag to divide the invoice into sections using display
1969 records (see L<FS::cust_bill_pkg_display>).  This is the "traditional"
1970 behavior.  Each section hash will have a 'category' element containing
1971 the section name from the display record (which probably equals the
1972 category name of the package, but may not in some cases).
1973
1974 summary: a flag indicating that this is a summary-format invoice.
1975 Turning this on has the following effects:
1976 - Ignores display items with the 'summary' flag.
1977 - Places all sections in the "early" group even if they have post_total.
1978 - Creates sections for all non-disabled package categories, even if they
1979 have no charges on this invoice, as well as a section with no name.
1980
1981 escape: an escape function to use for section titles.
1982
1983 extra_sections: an arrayref of additional sections to return after the
1984 sorted list.  If there are any of these, section subtotals exclude
1985 usage charges.
1986
1987 format: 'latex', 'html', or 'template' (i.e. text).  Not used, but
1988 passed through to C<_condense_section()>.
1989
1990 =cut
1991
1992 use vars qw(%pkg_category_cache);
1993 sub _items_sections {
1994   my $self = shift;
1995   my %opt = @_;
1996
1997   my $escape = $opt{escape};
1998   my @extra_sections = @{ $opt{extra_sections} || [] };
1999
2000   # $subtotal{$locationnum}{$categoryname} = amount.
2001   # if we're not using by_location, $locationnum is undef.
2002   # if we're not using by_category, you guessed it, $categoryname is undef.
2003   # if we're not using either one, we shouldn't be here in the first place...
2004   my %subtotal = ();
2005   my %late_subtotal = ();
2006   my %not_tax = ();
2007
2008   # About tax items + multisection invoices:
2009   # If either invoice_*summary option is enabled, AND there is a
2010   # package category with the name of the tax, then there will be
2011   # a display record assigning the tax item to that category.
2012   #
2013   # However, the taxes are always placed in the "Taxes, Surcharges,
2014   # and Fees" section regardless of that.  The only effect of the
2015   # display record is to create a subtotal for the summary page.
2016
2017   # cache these
2018   my $pkg_hash = $self->cust_pkg_hash;
2019
2020   foreach my $cust_bill_pkg ( $self->cust_bill_pkg )
2021   {
2022
2023       my $usage = $cust_bill_pkg->usage;
2024
2025       my $locationnum;
2026       if ( $opt{by_location} ) {
2027         if ( $cust_bill_pkg->pkgnum ) {
2028           $locationnum = $pkg_hash->{ $cust_bill_pkg->pkgnum }->locationnum;
2029         } else {
2030           $locationnum = '';
2031         }
2032       } else {
2033         $locationnum = undef;
2034       }
2035
2036       # as in _items_cust_pkg, if a line item has no display records,
2037       # cust_bill_pkg_display() returns a default record for it
2038
2039       foreach my $display ($cust_bill_pkg->cust_bill_pkg_display) {
2040         next if ( $display->summary && $opt{summary} );
2041
2042         my $section = $display->section;
2043         my $type    = $display->type;
2044         # Set $section = undef if we're sectioning by location and this
2045         # line item _has_ a location (i.e. isn't a fee).
2046         $section = undef if $locationnum;
2047
2048         # set this flag if the section is not tax-only
2049         $not_tax{$locationnum}{$section} = 1
2050           if $cust_bill_pkg->pkgnum  or $cust_bill_pkg->feepart;
2051
2052         # there's actually a very important piece of logic buried in here:
2053         # incrementing $late_subtotal{$section} CREATES
2054         # $late_subtotal{$section}.  keys(%late_subtotal) is later used
2055         # to define the list of late sections, and likewise keys(%subtotal).
2056         # When _items_cust_bill_pkg is called to generate line items for
2057         # real, it will be called with 'section' => $section for each
2058         # of these.
2059         if ( $display->post_total && !$opt{summary} ) {
2060           if (! $type || $type eq 'S') {
2061             $late_subtotal{$locationnum}{$section} += $cust_bill_pkg->setup
2062               if $cust_bill_pkg->setup != 0
2063               || $cust_bill_pkg->setup_show_zero;
2064           }
2065
2066           if (! $type) {
2067             $late_subtotal{$locationnum}{$section} += $cust_bill_pkg->recur
2068               if $cust_bill_pkg->recur != 0
2069               || $cust_bill_pkg->recur_show_zero;
2070           }
2071
2072           if ($type && $type eq 'R') {
2073             $late_subtotal{$locationnum}{$section} += $cust_bill_pkg->recur - $usage
2074               if $cust_bill_pkg->recur != 0
2075               || $cust_bill_pkg->recur_show_zero;
2076           }
2077
2078           if ($type && $type eq 'U') {
2079             $late_subtotal{$locationnum}{$section} += $usage
2080               unless scalar(@extra_sections);
2081           }
2082
2083         } else { # it's a pre-total (normal) section
2084
2085           # skip tax items unless they're explicitly included in a section
2086           next if $cust_bill_pkg->pkgnum == 0 and
2087                   ! $cust_bill_pkg->feepart   and
2088                   ! $section;
2089
2090           if ( $type eq 'S' ) {
2091             $subtotal{$locationnum}{$section} += $cust_bill_pkg->setup
2092               if $cust_bill_pkg->setup != 0
2093               || $cust_bill_pkg->setup_show_zero;
2094           } elsif ( $type eq 'R' ) {
2095             $subtotal{$locationnum}{$section} += $cust_bill_pkg->recur - $usage
2096               if $cust_bill_pkg->recur != 0
2097               || $cust_bill_pkg->recur_show_zero;
2098           } elsif ( $type eq 'U' ) {
2099             $subtotal{$locationnum}{$section} += $usage
2100               unless scalar(@extra_sections);
2101           } elsif ( !$type ) {
2102             $subtotal{$locationnum}{$section} += $cust_bill_pkg->setup
2103                                                + $cust_bill_pkg->recur;
2104           }
2105
2106         }
2107
2108       }
2109
2110   }
2111
2112   %pkg_category_cache = ();
2113
2114   # summary invoices need subtotals for all non-disabled package categories,
2115   # even if they're zero
2116   # but currently assume that there are no location sections, or at least
2117   # that the summary page doesn't care about them
2118   if ( $opt{summary} ) {
2119     foreach my $category (qsearch('pkg_category', {disabled => ''})) {
2120       $subtotal{''}{$category->categoryname} ||= 0;
2121     }
2122     $subtotal{''}{''} ||= 0;
2123   }
2124
2125   my @sections;
2126   foreach my $post_total (0,1) {
2127     my @these;
2128     my $s = $post_total ? \%late_subtotal : \%subtotal;
2129     foreach my $locationnum (keys %$s) {
2130       foreach my $sectionname (keys %{ $s->{$locationnum} }) {
2131         my $section = {
2132                         'subtotal'    => $s->{$locationnum}{$sectionname},
2133                         'post_total'  => $post_total,
2134                         'sort_weight' => 0,
2135                       };
2136         if ( $locationnum ) {
2137           $section->{'locationnum'} = $locationnum;
2138           my $location = FS::cust_location->by_key($locationnum);
2139           $section->{'description'} = &{ $escape }($location->location_label);
2140           # Better ideas? This will roughly group them by proximity,
2141           # which alpha sorting on any of the address fields won't.
2142           # Sorting by locationnum is meaningless.
2143           # We have to sort on _something_ or the order may change
2144           # randomly from one invoice to the next, which will confuse
2145           # people.
2146           $section->{'sort_weight'} = sprintf('%012s',$location->zip) .
2147                                       $locationnum;
2148           $section->{'location'} = {
2149             label_prefix => &{ $escape }($location->label_prefix),
2150             map { $_ => &{ $escape }($location->get($_)) }
2151               $location->fields
2152           };
2153         } else {
2154           $section->{'category'} = $sectionname;
2155           $section->{'description'} = &{ $escape }($sectionname);
2156           if ( _pkg_category($_) ) {
2157             $section->{'sort_weight'} = _pkg_category($_)->weight;
2158             if ( _pkg_category($_)->condense ) {
2159               $section = { %$section, $self->_condense_section($opt{format}) };
2160             }
2161           }
2162         }
2163         if ( !$post_total and !$not_tax{$locationnum}{$sectionname} ) {
2164           # then it's a tax-only section
2165           $section->{'summarized'} = 'Y';
2166           $section->{'tax_section'} = 'Y';
2167         }
2168         push @these, $section;
2169       } # foreach $sectionname
2170     } #foreach $locationnum
2171     push @these, @extra_sections if $post_total == 0;
2172     # need an alpha sort for location sections, because postal codes can
2173     # be non-numeric
2174     $sections[ $post_total ] = [ sort {
2175       $opt{'by_location'} ?
2176         ($a->{sort_weight} cmp $b->{sort_weight}) :
2177         ($a->{sort_weight} <=> $b->{sort_weight})
2178       } @these ];
2179   } #foreach $post_total
2180
2181   return @sections; # early, late
2182 }
2183
2184 #helper subs for above
2185
2186 sub cust_pkg_hash {
2187   my $self = shift;
2188   $self->{cust_pkg} ||= { map { $_->pkgnum => $_ } $self->cust_pkg };
2189 }
2190
2191 sub _pkg_category {
2192   my $categoryname = shift;
2193   $pkg_category_cache{$categoryname} ||=
2194     qsearchs( 'pkg_category', { 'categoryname' => $categoryname } );
2195 }
2196
2197 my %condensed_format = (
2198   'label' => [ qw( Description Qty Amount ) ],
2199   'fields' => [
2200                 sub { shift->{description} },
2201                 sub { shift->{quantity} },
2202                 sub { my($href, %opt) = @_;
2203                       ($opt{dollar} || ''). $href->{amount};
2204                     },
2205               ],
2206   'align'  => [ qw( l r r ) ],
2207   'span'   => [ qw( 5 1 1 ) ],            # unitprices?
2208   'width'  => [ qw( 10.7cm 1.4cm 1.6cm ) ],   # don't like this
2209 );
2210
2211 sub _condense_section {
2212   my ( $self, $format ) = ( shift, shift );
2213   ( 'condensed' => 1,
2214     map { my $method = "_condensed_$_"; $_ => $self->$method($format) }
2215       qw( description_generator
2216           header_generator
2217           total_generator
2218           total_line_generator
2219         )
2220   );
2221 }
2222
2223 sub _condensed_generator_defaults {
2224   my ( $self, $format ) = ( shift, shift );
2225   return ( \%condensed_format, ' ', ' ', ' ', sub { shift } );
2226 }
2227
2228 my %html_align = (
2229   'c' => 'center',
2230   'l' => 'left',
2231   'r' => 'right',
2232 );
2233
2234 sub _condensed_header_generator {
2235   my ( $self, $format ) = ( shift, shift );
2236
2237   my ( $f, $prefix, $suffix, $separator, $column ) =
2238     _condensed_generator_defaults($format);
2239
2240   if ($format eq 'latex') {
2241     $prefix = "\\hline\n\\rule{0pt}{2.5ex}\n\\makebox[1.4cm]{}&\n";
2242     $suffix = "\\\\\n\\hline";
2243     $separator = "&\n";
2244     $column =
2245       sub { my ($d,$a,$s,$w) = @_;
2246             return "\\multicolumn{$s}{$a}{\\makebox[$w][$a]{\\textbf{$d}}}";
2247           };
2248   } elsif ( $format eq 'html' ) {
2249     $prefix = '<th></th>';
2250     $suffix = '';
2251     $separator = '';
2252     $column =
2253       sub { my ($d,$a,$s,$w) = @_;
2254             return qq!<th align="$html_align{$a}">$d</th>!;
2255       };
2256   }
2257
2258   sub {
2259     my @args = @_;
2260     my @result = ();
2261
2262     foreach  (my $i = 0; $f->{label}->[$i]; $i++) {
2263       push @result,
2264         &{$column}( map { $f->{$_}->[$i] } qw(label align span width) );
2265     }
2266
2267     $prefix. join($separator, @result). $suffix;
2268   };
2269
2270 }
2271
2272 sub _condensed_description_generator {
2273   my ( $self, $format ) = ( shift, shift );
2274
2275   my ( $f, $prefix, $suffix, $separator, $column ) =
2276     _condensed_generator_defaults($format);
2277
2278   my $money_char = '$';
2279   if ($format eq 'latex') {
2280     $prefix = "\\hline\n\\multicolumn{1}{c}{\\rule{0pt}{2.5ex}~} &\n";
2281     $suffix = '\\\\';
2282     $separator = " & \n";
2283     $column =
2284       sub { my ($d,$a,$s,$w) = @_;
2285             return "\\multicolumn{$s}{$a}{\\makebox[$w][$a]{\\textbf{$d}}}";
2286           };
2287     $money_char = '\\dollar';
2288   }elsif ( $format eq 'html' ) {
2289     $prefix = '"><td align="center"></td>';
2290     $suffix = '';
2291     $separator = '';
2292     $column =
2293       sub { my ($d,$a,$s,$w) = @_;
2294             return qq!<td align="$html_align{$a}">$d</td>!;
2295       };
2296     #$money_char = $conf->config('money_char') || '$';
2297     $money_char = '';  # this is madness
2298   }
2299
2300   sub {
2301     #my @args = @_;
2302     my $href = shift;
2303     my @result = ();
2304
2305     foreach  (my $i = 0; $f->{label}->[$i]; $i++) {
2306       my $dollar = '';
2307       $dollar = $money_char if $i == scalar(@{$f->{label}})-1;
2308       push @result,
2309         &{$column}( &{$f->{fields}->[$i]}($href, 'dollar' => $dollar),
2310                     map { $f->{$_}->[$i] } qw(align span width)
2311                   );
2312     }
2313
2314     $prefix. join( $separator, @result ). $suffix;
2315   };
2316
2317 }
2318
2319 sub _condensed_total_generator {
2320   my ( $self, $format ) = ( shift, shift );
2321
2322   my ( $f, $prefix, $suffix, $separator, $column ) =
2323     _condensed_generator_defaults($format);
2324   my $style = '';
2325
2326   if ($format eq 'latex') {
2327     $prefix = "& ";
2328     $suffix = "\\\\\n";
2329     $separator = " & \n";
2330     $column =
2331       sub { my ($d,$a,$s,$w) = @_;
2332             return "\\multicolumn{$s}{$a}{\\makebox[$w][$a]{$d}}";
2333           };
2334   }elsif ( $format eq 'html' ) {
2335     $prefix = '';
2336     $suffix = '';
2337     $separator = '';
2338     $style = 'border-top: 3px solid #000000;border-bottom: 3px solid #000000;';
2339     $column =
2340       sub { my ($d,$a,$s,$w) = @_;
2341             return qq!<td align="$html_align{$a}" style="$style">$d</td>!;
2342       };
2343   }
2344
2345
2346   sub {
2347     my @args = @_;
2348     my @result = ();
2349
2350     #  my $r = &{$f->{fields}->[$i]}(@args);
2351     #  $r .= ' Total' unless $i;
2352
2353     foreach  (my $i = 0; $f->{label}->[$i]; $i++) {
2354       push @result,
2355         &{$column}( &{$f->{fields}->[$i]}(@args). ($i ? '' : ' Total'),
2356                     map { $f->{$_}->[$i] } qw(align span width)
2357                   );
2358     }
2359
2360     $prefix. join( $separator, @result ). $suffix;
2361   };
2362
2363 }
2364
2365 =item total_line_generator FORMAT
2366
2367 Returns a coderef used for generation of invoice total line items for this
2368 usage_class.  FORMAT is either html or latex
2369
2370 =cut
2371
2372 # should not be used: will have issues with hash element names (description vs
2373 # total_item and amount vs total_amount -- another array of functions?
2374
2375 sub _condensed_total_line_generator {
2376   my ( $self, $format ) = ( shift, shift );
2377
2378   my ( $f, $prefix, $suffix, $separator, $column ) =
2379     _condensed_generator_defaults($format);
2380   my $style = '';
2381
2382   if ($format eq 'latex') {
2383     $prefix = "& ";
2384     $suffix = "\\\\\n";
2385     $separator = " & \n";
2386     $column =
2387       sub { my ($d,$a,$s,$w) = @_;
2388             return "\\multicolumn{$s}{$a}{\\makebox[$w][$a]{$d}}";
2389           };
2390   }elsif ( $format eq 'html' ) {
2391     $prefix = '';
2392     $suffix = '';
2393     $separator = '';
2394     $style = 'border-top: 3px solid #000000;border-bottom: 3px solid #000000;';
2395     $column =
2396       sub { my ($d,$a,$s,$w) = @_;
2397             return qq!<td align="$html_align{$a}" style="$style">$d</td>!;
2398       };
2399   }
2400
2401
2402   sub {
2403     my @args = @_;
2404     my @result = ();
2405
2406     foreach  (my $i = 0; $f->{label}->[$i]; $i++) {
2407       push @result,
2408         &{$column}( &{$f->{fields}->[$i]}(@args),
2409                     map { $f->{$_}->[$i] } qw(align span width)
2410                   );
2411     }
2412
2413     $prefix. join( $separator, @result ). $suffix;
2414   };
2415
2416 }
2417
2418 =item _items_pkg [ OPTIONS ]
2419
2420 Return line item hashes for each package item on this invoice. Nearly
2421 equivalent to
2422
2423 $self->_items_cust_bill_pkg([ $self->cust_bill_pkg ])
2424
2425 The only OPTIONS accepted is 'section', which may point to a hashref
2426 with a key named 'condensed', which may have a true value.  If it
2427 does, this method tries to merge identical items into items with
2428 'quantity' equal to the number of items (not the sum of their
2429 separate quantities, for some reason).
2430
2431 =cut
2432
2433 sub _items_nontax {
2434   my $self = shift;
2435   # The order of these is important.  Bundled line items will be merged into
2436   # the most recent non-hidden item, so it needs to be the one with:
2437   # - the same pkgnum
2438   # - the same start date
2439   # - no pkgpart_override
2440   #
2441   # So: sort by pkgnum,
2442   # then by sdate
2443   # then sort the base line item before any overrides
2444   # then sort hidden before non-hidden add-ons
2445   # then sort by override pkgpart (for consistency)
2446   sort { $a->pkgnum <=> $b->pkgnum        or
2447          $a->sdate  <=> $b->sdate         or
2448          ($a->pkgpart_override ? 0 : -1)  or
2449          ($b->pkgpart_override ? 0 : 1)   or
2450          $b->hidden cmp $a->hidden        or
2451          $a->pkgpart_override <=> $b->pkgpart_override
2452        }
2453   # and of course exclude taxes and fees
2454   grep { $_->pkgnum > 0 } $self->cust_bill_pkg;
2455 }
2456
2457 sub _items_fee {
2458   my $self = shift;
2459   my %options = @_;
2460   my @cust_bill_pkg = grep { $_->feepart } $self->cust_bill_pkg;
2461   my @items;
2462   foreach my $cust_bill_pkg (@cust_bill_pkg) {
2463     # cache this, so we don't look it up again in every section
2464     my $part_fee = $cust_bill_pkg->get('part_fee')
2465        || $cust_bill_pkg->part_fee;
2466     $cust_bill_pkg->set('part_fee', $part_fee);
2467     if (!$part_fee) {
2468       #die "fee definition not found for line item #".$cust_bill_pkg->billpkgnum."\n"; # might make more sense
2469       warn "fee definition not found for line item #".$cust_bill_pkg->billpkgnum."\n";
2470       next;
2471     }
2472     if ( exists($options{section}) and exists($options{section}{category}) )
2473     {
2474       my $categoryname = $options{section}{category};
2475       # then filter for items that have that section
2476       if ( $part_fee->categoryname ne $categoryname ) {
2477         warn "skipping fee '".$part_fee->itemdesc."'--not in section $categoryname\n" if $DEBUG;
2478         next;
2479       }
2480     } # otherwise include them all in the main section
2481     # XXX what to do when sectioning by location?
2482
2483     my @ext_desc;
2484     my %base_invnums; # invnum => invoice date
2485     foreach ($cust_bill_pkg->cust_bill_pkg_fee) {
2486       if ($_->base_invnum) {
2487         my $base_bill = FS::cust_bill->by_key($_->base_invnum);
2488         my $base_date = $self->time2str_local('short', $base_bill->_date)
2489           if $base_bill;
2490         $base_invnums{$_->base_invnum} = $base_date || '';
2491       }
2492     }
2493     foreach (sort keys(%base_invnums)) {
2494       next if $_ == $self->invnum;
2495       push @ext_desc,
2496         $self->mt('from invoice \\#[_1] on [_2]', $_, $base_invnums{$_});
2497     }
2498     push @items,
2499       { feepart     => $cust_bill_pkg->feepart,
2500         amount      => sprintf('%.2f', $cust_bill_pkg->setup + $cust_bill_pkg->recur),
2501         description => $part_fee->itemdesc_locale($self->cust_main->locale),
2502         ext_description => \@ext_desc
2503         # sdate/edate?
2504       };
2505   }
2506   @items;
2507 }
2508
2509 sub _items_pkg {
2510   my $self = shift;
2511   my %options = @_;
2512
2513   warn "$me _items_pkg searching for all package line items\n"
2514     if $DEBUG > 1;
2515
2516   my @cust_bill_pkg = $self->_items_nontax;
2517
2518   warn "$me _items_pkg filtering line items\n"
2519     if $DEBUG > 1;
2520   my @items = $self->_items_cust_bill_pkg(\@cust_bill_pkg, @_);
2521
2522   if ($options{section} && $options{section}->{condensed}) {
2523
2524     warn "$me _items_pkg condensing section\n"
2525       if $DEBUG > 1;
2526
2527     my %itemshash = ();
2528     local $Storable::canonical = 1;
2529     foreach ( @items ) {
2530       my $item = { %$_ };
2531       delete $item->{ref};
2532       delete $item->{ext_description};
2533       my $key = freeze($item);
2534       $itemshash{$key} ||= 0;
2535       $itemshash{$key} ++; # += $item->{quantity};
2536     }
2537     @items = sort { $a->{description} cmp $b->{description} }
2538              map { my $i = thaw($_);
2539                    $i->{quantity} = $itemshash{$_};
2540                    $i->{amount} =
2541                      sprintf( "%.2f", $i->{quantity} * $i->{amount} );#unit_amount
2542                    $i;
2543                  }
2544              keys %itemshash;
2545   }
2546
2547   warn "$me _items_pkg returning ". scalar(@items). " items\n"
2548     if $DEBUG > 1;
2549
2550   @items;
2551 }
2552
2553 sub _taxsort {
2554   return 0 unless $a->itemdesc cmp $b->itemdesc;
2555   return -1 if $b->itemdesc eq 'Tax';
2556   return 1 if $a->itemdesc eq 'Tax';
2557   return -1 if $b->itemdesc eq 'Other surcharges';
2558   return 1 if $a->itemdesc eq 'Other surcharges';
2559   $a->itemdesc cmp $b->itemdesc;
2560 }
2561
2562 sub _items_tax {
2563   my $self = shift;
2564   my @cust_bill_pkg = sort _taxsort grep { ! $_->pkgnum and ! $_->feepart }
2565     $self->cust_bill_pkg;
2566   my @items = $self->_items_cust_bill_pkg(\@cust_bill_pkg, @_);
2567
2568   if ( $self->conf->exists('always_show_tax') ) {
2569     my $itemdesc = $self->conf->config('always_show_tax') || 'Tax';
2570     if (0 == grep { $_->{description} eq $itemdesc } @items) {
2571       push @items,
2572         { 'description' => $itemdesc,
2573           'amount'      => 0.00 };
2574     }
2575   }
2576   @items;
2577 }
2578
2579 =item _items_cust_bill_pkg CUST_BILL_PKGS OPTIONS
2580
2581 Takes an arrayref of L<FS::cust_bill_pkg> objects, and returns a
2582 list of hashrefs describing the line items they generate on the invoice.
2583
2584 OPTIONS may include:
2585
2586 format: the invoice format.
2587
2588 escape_function: the function used to escape strings.
2589
2590 DEPRECATED? (expensive, mostly unused?)
2591 format_function: the function used to format CDRs.
2592
2593 section: a hashref containing 'category' and/or 'locationnum'; if this
2594 is present, only returns line items that belong to that category and/or
2595 location (whichever is defined).
2596
2597 multisection: a flag indicating that this is a multisection invoice,
2598 which does something complicated.
2599
2600 preref_callback: coderef run for each line item, code should return HTML to be
2601 displayed before that line item (quotations only)
2602
2603 Returns a list of hashrefs, each of which may contain:
2604
2605 pkgnum, description, amount, unit_amount, quantity, pkgpart, _is_setup, and
2606 ext_description, which is an arrayref of detail lines to show below
2607 the package line.
2608
2609 =cut
2610
2611 sub _items_cust_bill_pkg {
2612   my $self = shift;
2613   my $conf = $self->conf;
2614   my $cust_bill_pkgs = shift;
2615   my %opt = @_;
2616
2617   my $format = $opt{format} || '';
2618   my $escape_function = $opt{escape_function} || sub { shift };
2619   my $format_function = $opt{format_function} || '';
2620   my $no_usage = $opt{no_usage} || '';
2621   my $unsquelched = $opt{unsquelched} || ''; #unused
2622   my ($section, $locationnum, $category);
2623   if ( $opt{section} ) {
2624     $category = $opt{section}->{category};
2625     $locationnum = $opt{section}->{locationnum};
2626   }
2627   my $summary_page = $opt{summary_page} || ''; #unused
2628   my $multisection = defined($category) || defined($locationnum);
2629   my $discount_show_always = 0;
2630
2631   my $maxlength = $conf->config('cust_bill-latex_lineitem_maxlength') || 50;
2632
2633   my $cust_main = $self->cust_main;#for per-agent cust_bill-line_item-ate_style
2634                                    # and location labels
2635
2636   my @b = (); # accumulator for the line item hashes that we'll return
2637   my ($s, $r, $u, $d) = ( undef, undef, undef );
2638             # the 'current' line item hashes for setup, recur, usage, discount
2639   foreach my $cust_bill_pkg ( @$cust_bill_pkgs )
2640   {
2641     # if the current line item is waiting to go out, and the one we're about
2642     # to start is not bundled, then push out the current one and start a new
2643     # one.
2644     foreach ( $s, $r, ($opt{skip_usage} ? () : $u ) , $d ) {
2645       if ( $_ && !$cust_bill_pkg->hidden ) {
2646         $_->{amount}      = sprintf( "%.2f", $_->{amount} );
2647         $_->{amount}      =~ s/^\-0\.00$/0.00/;
2648         if (exists($_->{unit_amount})) {
2649           $_->{unit_amount} = sprintf( "%.2f", $_->{unit_amount} );
2650         }
2651         push @b, { %$_ }
2652           if $_->{amount} != 0
2653           || $discount_show_always
2654           || ( ! $_->{_is_setup} && $_->{recur_show_zero} )
2655           || (   $_->{_is_setup} && $_->{setup_show_zero} )
2656         ;
2657         $_ = undef;
2658       }
2659     }
2660
2661     if ( $locationnum ) {
2662       # this is a location section; skip packages that aren't at this
2663       # service location.
2664       next if $cust_bill_pkg->pkgnum == 0; # skips fees...
2665       next if $self->cust_pkg_hash->{ $cust_bill_pkg->pkgnum }->locationnum
2666               != $locationnum;
2667     }
2668
2669     # Consider display records for this item to determine if it belongs
2670     # in this section.  Note that if there are no display records, there
2671     # will be a default pseudo-record that includes all charge types
2672     # and has no section name.
2673     my @cust_bill_pkg_display = $cust_bill_pkg->can('cust_bill_pkg_display')
2674                                   ? $cust_bill_pkg->cust_bill_pkg_display
2675                                   : ( $cust_bill_pkg );
2676
2677     warn "$me _items_cust_bill_pkg considering cust_bill_pkg ".
2678          $cust_bill_pkg->billpkgnum. ", pkgnum ". $cust_bill_pkg->pkgnum. "\n"
2679       if $DEBUG > 1;
2680
2681     if ( defined($category) ) {
2682       # then this is a package category section; process all display records
2683       # that belong to this section.
2684       @cust_bill_pkg_display = grep { $_->section eq $category }
2685                                 @cust_bill_pkg_display;
2686     } else {
2687       # otherwise, process all display records that aren't usage summaries
2688       # (I don't think there should be usage summaries if you aren't using
2689       # category sections, but this is the historical behavior)
2690       @cust_bill_pkg_display = grep { !$_->summary }
2691                                 @cust_bill_pkg_display;
2692     }
2693
2694     my $classname = ''; # package class name, will fill in later
2695
2696     foreach my $display (@cust_bill_pkg_display) {
2697
2698       warn "$me _items_cust_bill_pkg considering cust_bill_pkg_display ".
2699            $display->billpkgdisplaynum. "\n"
2700         if $DEBUG > 1;
2701
2702       my $type = $display->type;
2703
2704       my $desc = $cust_bill_pkg->desc( $cust_main ? $cust_main->locale : '' );
2705       $desc = substr($desc, 0, $maxlength). '...'
2706         if $format eq 'latex' && length($desc) > $maxlength;
2707
2708       my %details_opt = ( 'format'          => $format,
2709                           'escape_function' => $escape_function,
2710                           'format_function' => $format_function,
2711                           'no_usage'        => $opt{'no_usage'},
2712                         );
2713
2714       if ( ref($cust_bill_pkg) eq 'FS::quotation_pkg' ) {
2715
2716         warn "$me _items_cust_bill_pkg cust_bill_pkg is quotation_pkg\n"
2717           if $DEBUG > 1;
2718         # quotation_pkgs are never fees, so don't worry about the case where
2719         # part_pkg is undefined
2720
2721         # and I guess they're never bundled either?
2722         if ( $cust_bill_pkg->setup != 0 ) {
2723           my $description = $desc;
2724           $description .= ' Setup'
2725             if $cust_bill_pkg->recur != 0
2726             || $discount_show_always
2727             || $cust_bill_pkg->recur_show_zero;
2728           push @b, {
2729             'pkgnum'      => $cust_bill_pkg->pkgpart, #so it displays in Ref
2730             'description' => $description,
2731             'amount'      => sprintf("%.2f", $cust_bill_pkg->setup),
2732             'unit_amount'   => sprintf("%.2f", $cust_bill_pkg->unitsetup),
2733             'quantity'    => $cust_bill_pkg->quantity,
2734             'preref_html' => ( $opt{preref_callback}
2735                                  ? &{ $opt{preref_callback} }( $cust_bill_pkg )
2736                                  : ''
2737                              ),
2738           };
2739         }
2740         if ( $cust_bill_pkg->recur != 0 ) {
2741           push @b, {
2742             'pkgnum'      => $cust_bill_pkg->pkgpart, #so it displays in Ref
2743             'description' => "$desc (". $cust_bill_pkg->part_pkg->freq_pretty.")",
2744             'amount'      => sprintf("%.2f", $cust_bill_pkg->recur),
2745             'unit_amount'   => sprintf("%.2f", $cust_bill_pkg->unitrecur),
2746             'quantity'    => $cust_bill_pkg->quantity,
2747             'preref_html' => ( $opt{preref_callback}
2748                                  ? &{ $opt{preref_callback} }( $cust_bill_pkg )
2749                                  : ''
2750                              ),
2751           };
2752         }
2753
2754       } elsif ( $cust_bill_pkg->pkgnum > 0 ) {
2755         # a "normal" package line item (not a quotation, not a fee, not a tax)
2756
2757         warn "$me _items_cust_bill_pkg cust_bill_pkg is non-tax\n"
2758           if $DEBUG > 1;
2759
2760         my $cust_pkg = $cust_bill_pkg->cust_pkg;
2761         my $part_pkg = $cust_pkg->part_pkg;
2762
2763         # which pkgpart to show for display purposes?
2764         my $pkgpart = $cust_bill_pkg->pkgpart_override || $cust_pkg->pkgpart;
2765
2766         # start/end dates for invoice formats that do nonstandard
2767         # things with them
2768         my %item_dates = ();
2769         %item_dates = map { $_ => $cust_bill_pkg->$_ } ('sdate', 'edate')
2770           unless $part_pkg->option('disable_line_item_date_ranges',1);
2771
2772         # not normally used, but pass this to the template anyway
2773         $classname = $part_pkg->classname;
2774
2775         if (    (!$type || $type eq 'S')
2776              && (    $cust_bill_pkg->setup != 0
2777                   || $cust_bill_pkg->setup_show_zero
2778                 )
2779            )
2780          {
2781
2782           warn "$me _items_cust_bill_pkg adding setup\n"
2783             if $DEBUG > 1;
2784
2785           my $description = $desc;
2786           $description .= ' Setup'
2787             if $cust_bill_pkg->recur != 0
2788             || $discount_show_always
2789             || $cust_bill_pkg->recur_show_zero;
2790
2791           $description .= $cust_bill_pkg->time_period_pretty( $part_pkg,
2792                                                               $self->agentnum )
2793             if $part_pkg->is_prepaid #for prepaid, "display the validity period
2794                                      # triggered by the recurring charge freq
2795                                      # (RT#26274)
2796             && $cust_bill_pkg->recur == 0
2797             && ! $cust_bill_pkg->recur_show_zero;
2798
2799           my @d = ();
2800           my $svc_label;
2801
2802           # always pass the svc_label through to the template, even if
2803           # not displaying it as an ext_description
2804           my @svc_labels = map &{$escape_function}($_),
2805                       $cust_pkg->h_labels_short($self->_date, undef, 'I');
2806
2807           $svc_label = $svc_labels[0];
2808
2809           unless ( $cust_pkg->part_pkg->hide_svc_detail
2810                 || $cust_bill_pkg->hidden )
2811           {
2812
2813             push @d, @svc_labels
2814               unless $cust_bill_pkg->pkgpart_override; #don't redisplay services
2815             my $lnum = $cust_main ? $cust_main->ship_locationnum
2816                                   : $self->prospect_main->locationnum;
2817             # show the location label if it's not the customer's default
2818             # location, and we're not grouping items by location already
2819             if ( $cust_pkg->locationnum != $lnum and !defined($locationnum) ) {
2820               my $loc = $cust_pkg->location_label;
2821               $loc = substr($loc, 0, $maxlength). '...'
2822                 if $format eq 'latex' && length($loc) > $maxlength;
2823               push @d, &{$escape_function}($loc);
2824             }
2825
2826           } #unless hiding service details
2827
2828           push @d, $cust_bill_pkg->details(%details_opt)
2829             if $cust_bill_pkg->recur == 0;
2830
2831           if ( $cust_bill_pkg->hidden ) {
2832             $s->{amount}      += $cust_bill_pkg->setup;
2833             $s->{unit_amount} += $cust_bill_pkg->unitsetup;
2834             push @{ $s->{ext_description} }, @d;
2835           } else {
2836             $s = {
2837               _is_setup       => 1,
2838               description     => $description,
2839               pkgpart         => $pkgpart,
2840               pkgnum          => $cust_bill_pkg->pkgnum,
2841               amount          => $cust_bill_pkg->setup,
2842               setup_show_zero => $cust_bill_pkg->setup_show_zero,
2843               unit_amount     => $cust_bill_pkg->unitsetup,
2844               quantity        => $cust_bill_pkg->quantity,
2845               ext_description => \@d,
2846               svc_label       => ($svc_label || ''),
2847               locationnum     => $cust_pkg->locationnum, # sure, why not?
2848             };
2849           };
2850
2851         }
2852
2853         if (    ( !$type || $type eq 'R' || $type eq 'U' )
2854              && (
2855                      $cust_bill_pkg->recur != 0
2856                   || $cust_bill_pkg->setup == 0
2857                   || $discount_show_always
2858                   || $cust_bill_pkg->recur_show_zero
2859                 )
2860            )
2861         {
2862
2863           warn "$me _items_cust_bill_pkg adding recur/usage\n"
2864             if $DEBUG > 1;
2865
2866           my $is_summary = $display->summary;
2867           my $description = $desc;
2868           if ( $type eq 'U' and defined($r) ) {
2869             # don't just show the same description as the recur line
2870             $description = $self->mt('Usage charges');
2871           }
2872
2873           my $part_pkg = $cust_pkg->part_pkg;
2874
2875           $description .= $cust_bill_pkg->time_period_pretty( $part_pkg,
2876                                                               $self->agentnum );
2877
2878           my @d = ();
2879           my @seconds = (); # for display of usage info
2880           my $svc_label = '';
2881
2882           #at least until cust_bill_pkg has "past" ranges in addition to
2883           #the "future" sdate/edate ones... see #3032
2884           my @dates = ( $self->_date );
2885           my $prev = $cust_bill_pkg->previous_cust_bill_pkg;
2886           push @dates, $prev->sdate if $prev;
2887           push @dates, undef if !$prev;
2888
2889           my @svc_labels = map &{$escape_function}($_),
2890                       $cust_pkg->h_labels_short(@dates, 'I');
2891           $svc_label = $svc_labels[0];
2892
2893           # show service labels, unless...
2894                     # the package is set not to display them
2895           unless ( $part_pkg->hide_svc_detail
2896                     # or this is a tax-like line item
2897                 || $cust_bill_pkg->itemdesc
2898                     # or this is a hidden (bundled) line item
2899                 || $cust_bill_pkg->hidden
2900                     # or this is a usage summary line
2901                 || $is_summary && $type && $type eq 'U'
2902                     # or this is a usage line and there's a recurring line
2903                     # for the package in the same section (which will
2904                     # have service labels already)
2905                 || ($type eq 'U' and defined($r))
2906               )
2907           {
2908
2909             warn "$me _items_cust_bill_pkg adding service details\n"
2910               if $DEBUG > 1;
2911
2912             push @d, @svc_labels
2913               unless $cust_bill_pkg->pkgpart_override; #don't redisplay services
2914             warn "$me _items_cust_bill_pkg done adding service details\n"
2915               if $DEBUG > 1;
2916
2917             my $lnum = $cust_main ? $cust_main->ship_locationnum
2918                                   : $self->prospect_main->locationnum;
2919             # show the location label if it's not the customer's default
2920             # location, and we're not grouping items by location already
2921             if ( $cust_pkg->locationnum != $lnum and !defined($locationnum) ) {
2922               my $loc = $cust_pkg->location_label;
2923               $loc = substr($loc, 0, $maxlength). '...'
2924                 if $format eq 'latex' && length($loc) > $maxlength;
2925               push @d, &{$escape_function}($loc);
2926             }
2927
2928             # Display of seconds_since_sqlradacct:
2929             # On the invoice, when processing @detail_items, look for a field
2930             # named 'seconds'.  This will contain total seconds for each
2931             # service, in the same order as @ext_description.  For services
2932             # that don't support this it will show undef.
2933             if ( $conf->exists('svc_acct-usage_seconds')
2934                  and ! $cust_bill_pkg->pkgpart_override ) {
2935               foreach my $cust_svc (
2936                   $cust_pkg->h_cust_svc(@dates, 'I')
2937                 ) {
2938
2939                 # eval because not having any part_export_usage exports
2940                 # is a fatal error, last_bill/_date because that's how
2941                 # sqlradius_hour billing does it
2942                 my $sec = eval {
2943                   $cust_svc->seconds_since_sqlradacct($dates[1] || 0, $dates[0]);
2944                 };
2945                 push @seconds, $sec;
2946               }
2947             } #if svc_acct-usage_seconds
2948
2949           } # if we are showing service labels
2950
2951           unless ( $is_summary ) {
2952             warn "$me _items_cust_bill_pkg adding details\n"
2953               if $DEBUG > 1;
2954
2955             #instead of omitting details entirely in this case (unwanted side
2956             # effects), just omit CDRs
2957             $details_opt{'no_usage'} = 1
2958               if $type && $type eq 'R';
2959
2960             push @d, $cust_bill_pkg->details(%details_opt);
2961           }
2962
2963           warn "$me _items_cust_bill_pkg calculating amount\n"
2964             if $DEBUG > 1;
2965
2966           my $amount = 0;
2967           if (!$type) {
2968             $amount = $cust_bill_pkg->recur;
2969           } elsif ($type eq 'R') {
2970             $amount = $cust_bill_pkg->recur - $cust_bill_pkg->usage;
2971           } elsif ($type eq 'U') {
2972             $amount = $cust_bill_pkg->usage;
2973           }
2974
2975           if ( !$type || $type eq 'R' ) {
2976
2977             warn "$me _items_cust_bill_pkg adding recur\n"
2978               if $DEBUG > 1;
2979
2980             my $unit_amount =
2981               ( $cust_bill_pkg->unitrecur > 0 ) ? $cust_bill_pkg->unitrecur
2982                                                 : $amount;
2983
2984             if ( $cust_bill_pkg->hidden ) {
2985               $r->{amount}      += $amount;
2986               $r->{unit_amount} += $unit_amount;
2987               push @{ $r->{ext_description} }, @d;
2988             } else {
2989               $r = {
2990                 description     => $description,
2991                 pkgpart         => $pkgpart,
2992                 pkgnum          => $cust_bill_pkg->pkgnum,
2993                 amount          => $amount,
2994                 recur_show_zero => $cust_bill_pkg->recur_show_zero,
2995                 unit_amount     => $unit_amount,
2996                 quantity        => $cust_bill_pkg->quantity,
2997                 %item_dates,
2998                 ext_description => \@d,
2999                 svc_label       => ($svc_label || ''),
3000                 locationnum     => $cust_pkg->locationnum,
3001               };
3002               $r->{'seconds'} = \@seconds if grep {defined $_} @seconds;
3003             }
3004
3005           } else {  # $type eq 'U'
3006
3007             warn "$me _items_cust_bill_pkg adding usage\n"
3008               if $DEBUG > 1;
3009
3010             if ( $cust_bill_pkg->hidden and defined($u) ) {
3011               # if this is a hidden package and there's already a usage
3012               # line for the bundle, add this package's total amount and
3013               # usage details to it
3014               $u->{amount}      += $amount;
3015               push @{ $u->{ext_description} }, @d;
3016             } elsif ( $amount ) {
3017               # create a new usage line
3018               $u = {
3019                 description     => $description,
3020                 pkgpart         => $pkgpart,
3021                 pkgnum          => $cust_bill_pkg->pkgnum,
3022                 amount          => $amount,
3023                 usage_item      => 1,
3024                 recur_show_zero => $cust_bill_pkg->recur_show_zero,
3025                 %item_dates,
3026                 ext_description => \@d,
3027                 locationnum     => $cust_pkg->locationnum,
3028               };
3029             } # else this has no usage, so don't create a usage section
3030           }
3031
3032         } # recurring or usage with recurring charge
3033
3034         # decide whether to show active discounts here
3035         if (
3036             # case 1: we are showing a single line for the package
3037             ( !$type )
3038             # case 2: we are showing a setup line for a package that has
3039             # no base recurring fee
3040             or ( $type eq 'S' and $cust_bill_pkg->unitrecur == 0 )
3041             # case 3: we are showing a recur line for a package that has
3042             # a base recurring fee
3043             or ( $type eq 'R' and $cust_bill_pkg->unitrecur > 0 )
3044         ) {
3045
3046           my @discounts = $cust_bill_pkg->cust_bill_pkg_discount;
3047           # special case: if there are old "discount details" on this line
3048           # item, don't show discount line items
3049           if ( FS::cust_bill_pkg_detail->count(
3050               "detail LIKE 'Includes discount%' AND billpkgnum = " .
3051               $cust_bill_pkg->billpkgnum
3052              ) > 0 ) {
3053              @discounts = ();
3054           }
3055           if( @discounts ) {
3056             warn "$me _items_cust_bill_pkg including discounts for ".
3057               $cust_bill_pkg->billpkgnum."\n"
3058               if $DEBUG;
3059             my $discount_amount = sum( map {$_->amount} @discounts );
3060             my $orig_amount = $cust_bill_pkg->setup + $cust_bill_pkg->recur
3061                               + $discount_amount;
3062             # if multiple discounts apply to the same package, how to display
3063             # them? ext_description lines, apparently
3064             if ( $d and $cust_bill_pkg->hidden ) {
3065               $d->{amount}      += $discount_amount;
3066               $d->{orig_amount} += $orig_amount;
3067             } else {
3068               my @ext;
3069               # make a placeholder for the original price, if necessary
3070               # (if unit prices are enabled, it won't be necessary)
3071               push @ext, '' if !$conf->exists('invoice-unitprice');
3072               $d = {
3073                 _is_discount    => 1,
3074                 description     => $self->mt('Discount included'),
3075                 amount          => $discount_amount,
3076                 orig_amount     => $orig_amount,
3077                 ext_description => \@ext,
3078               };
3079               foreach my $cust_bill_pkg_discount (@discounts) {
3080                 my $def = $cust_bill_pkg_discount->cust_pkg_discount->discount;
3081                 push @ext, &{$escape_function}( $def->description );
3082               }
3083             }
3084
3085             # update the placeholder to show the original price in the
3086             # first ext_description line
3087             if ( !$conf->exists('invoice-unitprice') ) {
3088               $d->{ext_description}->[0] =
3089                 sprintf('Original price: %.2f', $d->{orig_amount});
3090             }
3091           } # if there are any discounts
3092         } # if this is an appropriate place to show discounts
3093
3094       } else { # taxes and fees
3095
3096         warn "$me _items_cust_bill_pkg cust_bill_pkg is tax\n"
3097           if $DEBUG > 1;
3098
3099         # items of this kind should normally not have sdate/edate.
3100         push @b, {
3101           'description' => $desc,
3102           'amount'      => sprintf('%.2f', $cust_bill_pkg->setup
3103                                            + $cust_bill_pkg->recur)
3104         };
3105
3106       } # if quotation / package line item / other line item
3107
3108     } # foreach $display
3109
3110     $discount_show_always = ($cust_bill_pkg->cust_bill_pkg_discount
3111                                 && $conf->exists('discount-show-always'));
3112
3113   }
3114
3115   foreach ( $s, $r, ($opt{skip_usage} ? () : $u, $d ) ) {
3116     if ( $_  ) {
3117       $_->{amount}      = sprintf( "%.2f", $_->{amount} ),
3118         if exists($_->{amount});
3119       $_->{amount}      =~ s/^\-0\.00$/0.00/;
3120       if (exists($_->{unit_amount})) {
3121         $_->{unit_amount} = sprintf( "%.2f", $_->{unit_amount} );
3122       }
3123
3124       push @b, { %$_ }
3125         if $_->{amount} != 0
3126         || $discount_show_always
3127         || ( ! $_->{_is_setup} && $_->{recur_show_zero} )
3128         || (   $_->{_is_setup} && $_->{setup_show_zero} )
3129     }
3130   }
3131
3132   warn "$me _items_cust_bill_pkg done considering cust_bill_pkgs\n"
3133     if $DEBUG > 1;
3134
3135   @b;
3136
3137 }
3138
3139 =item _items_discounts_avail
3140
3141 Returns an array of line item hashrefs representing available term discounts
3142 for this invoice.  This makes the same assumptions that apply to term
3143 discounts in general: that the package is billed monthly, at a flat rate,
3144 with no usage charges.  A prorated first month will be handled, as will
3145 a setup fee if the discount is allowed to apply to setup fees.
3146
3147 =cut
3148
3149 sub _items_discounts_avail {
3150   my $self = shift;
3151
3152   #maybe move this method from cust_bill when quotations support discount_plans
3153   return () unless $self->can('discount_plans');
3154   my %plans = $self->discount_plans;
3155
3156   my $list_pkgnums = 0; # if any packages are not eligible for all discounts
3157   $list_pkgnums = grep { $_->list_pkgnums } values %plans;
3158
3159   map {
3160     my $months = $_;
3161     my $plan = $plans{$months};
3162
3163     my $term_total = sprintf('%.2f', $plan->discounted_total);
3164     my $percent = sprintf('%.0f',
3165                           100 * (1 - $term_total / $plan->base_total) );
3166     my $permonth = sprintf('%.2f', $term_total / $months);
3167     my $detail = $self->mt('discount on item'). ' '.
3168                  join(', ', map { "#$_" } $plan->pkgnums)
3169       if $list_pkgnums;
3170
3171     # discounts for non-integer months don't work anyway
3172     $months = sprintf("%d", $months);
3173
3174     +{
3175       description => $self->mt('Save [_1]% by paying for [_2] months',
3176                                 $percent, $months),
3177       amount      => $self->mt('[_1] ([_2] per month)',
3178                                 $term_total, $money_char.$permonth),
3179       ext_description => ($detail || ''),
3180     }
3181   } #map
3182   sort { $b <=> $a } keys %plans;
3183
3184 }
3185
3186 1;