1 package FS::detail_format;
7 use FS::cust_bill_pkg_detail;
12 my $me = '[FS::detail_format]';
16 FS::detail_format - invoice detail formatter
20 An FS::detail_format object is a converter to create invoice details
21 (L<FS::cust_bill_pkg_detail>) from call detail records (L<FS::cdr>)
22 or other usage information. FS::detail_format inherits from nothing.
24 Subclasses of FS::detail_format represent specific detail formats.
30 =item new FORMAT, OPTIONS
32 Returns a new detail formatter. The FORMAT argument is the name of
37 - buffer: an arrayref to store details into. This may avoid the need for
38 a large copy operation at the end of processing. However, since
39 summary formats will produce nothing until the end of processing,
40 C<finish> must be called after all CDRs have been appended.
42 - inbound: a flag telling the formatter to format CDRs for display to
43 the receiving party, rather than the originator. In this case, the
44 L<FS::cdr_termination> object will be fetched and its values used for
45 rated_price, rated_seconds, rated_minutes, and svcnum. This can be
46 changed with the C<inbound> method.
48 - locale: a locale string to use for static text and date formats. This
55 if ( $class eq 'FS::detail_format' ) {
57 or die "$me format name required";
58 $class = "FS::detail_format::$format"
59 unless $format =~ /^FS::detail_format::/;
62 die "$me error loading $class: $@" if $@;
65 my $locale = $opt{'locale'} || '';
66 my $conf = FS::Conf->new(locale => $locale);
67 $locale ||= $conf->config('locale') || 'en_US';
69 my %locale_info = FS::Locales->locale_info($locale);
70 my $language_name = $locale_info{'name'};
72 my $self = { conf => FS::Conf->new(locale => $locale),
73 csv => Text::CSV_XS->new({ binary => 1 }),
74 inbound => ($opt{'inbound'} ? 1 : 0),
75 buffer => ($opt{'buffer'} || []),
76 _lh => FS::L10N->get_handle($locale),
77 _dh => eval { Date::Language->new($language_name) } ||
89 Set/get the 'inbound' flag.
95 $self->{inbound} = ($_[0] > 0) if (@_);
101 Takes any number of call detail records (as L<FS::cdr> objects),
102 formats them, and appends them to the internal buffer.
104 By default, this simply calls C<single_detail> on each CDR in the
105 set. Subclasses should override C<append> and maybe C<finish> if
106 they do not produce detail lines from CDRs in a 1:1 fashion.
108 The 'billpkgnum', 'invnum', 'pkgnum', and 'phonenum' fields will
116 push @{ $self->{buffer} }, $self->single_detail($_);
122 Returns all invoice detail records in the buffer. This will perform
123 a C<finish> first. Subclasses generally shouldn't override this.
135 Ensures that all invoice details are generated given the CDRs that
136 have been appended. By default, this does nothing.
144 Returns a header row for the format, as an L<FS::cust_bill_pkg_detail>
145 object. By default this has 'format' = 'C', 'detail' = the value
146 returned by C<header_detail>, and all other fields empty.
148 This is called after C<finish>, so it can use information from the CDRs.
155 FS::cust_bill_pkg_detail->new(
156 { 'format' => 'C', 'detail' => $self->mt($self->header_detail) }
160 =item single_detail CDR
162 Takes a single CDR and returns an invoice detail to describe it.
164 By default, this maps the following fields from the CDR:
166 rated_price => amount
167 rated_classnum => classnum
168 rated_seconds => duration
169 rated_regionname => regionname
170 accountcode => accountcode
171 startdate => startdate
173 It then calls C<columns> on the CDR to obtain a list of detail
174 columns, formats them as a CSV string, and stores that in the
183 my @columns = $self->columns($cdr);
184 my $status = $self->csv->combine(@columns);
185 die "$me error combining ".$self->csv->error_input."\n"
188 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
189 my $price = $object->rated_price if $object;
190 $price = 0 if $cdr->freesidestatus eq 'no-charge';
192 FS::cust_bill_pkg_detail->new( {
194 'classnum' => $cdr->rated_classnum,
195 'duration' => $cdr->rated_seconds,
196 'regionname' => $cdr->rated_regionname,
197 'accountcode' => $cdr->accountcode,
198 'startdate' => $cdr->startdate,
200 'detail' => $self->csv->string,
206 Returns a list of CSV columns (to be shown on the invoice) for
207 the CDR. This is the method most subclasses should override.
213 die "$me no columns method in ".ref($self);
218 Returns the 'detail' field for the header row. This should
219 probably be a CSV string of column headers for the values returned
226 die "$me no header_detail method in ".ref($self);
229 # convenience methods for subclasses
231 sub conf { $_[0]->{conf} }
233 sub csv { $_[0]->{csv} }
237 $self->{date_format} ||= ($self->conf->config('date_format') || '%m/%d/%Y');
242 $self->{money_char} ||= ($self->conf->config('money_char') || '$');
245 # localization methods
249 $self->{_dh}->time2str(@_);
254 $self->{_lh}->maketext(@_);
257 #imitate previous behavior for now
262 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
263 my $sec = $object->rated_seconds if $object;
265 # XXX termination objects don't have rated_granularity so this may
266 # result in inbound CDRs being displayed as min/sec when they shouldn't.
267 # Should probably fix this.
268 if ( $cdr->rated_granularity eq '0' ) {
271 elsif ( $cdr->rated_granularity eq '60' ) {
272 sprintf('%dm', ($sec + 59)/60);
275 sprintf('%dm %ds', $sec / 60, $sec % 60);
282 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
283 my $price = $object->rated_price if $object;
284 $price = '0.00' if $object->freesidestatus eq 'no-charge';
285 length($price) ? $self->money_char . $price : '';