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