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 a
38 large copy operation at the end of processing. However, since summary formats
39 will produce nothing until the end of processing, C<finish> must be called
40 after all CDRs have been appended.
42 - inbound: a flag telling the formatter to format CDRs for display to the
43 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 changed
46 with the C<inbound> method.
48 - locale: a locale string to use for static text and date formats. This is
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) } ||
91 Set/get the 'inbound' flag.
97 $self->{inbound} = ($_[0] > 0) if (@_);
103 Set/get the locally meaningful phone number. This is used to tag call details
104 for presentation on certain kinds of invoices.
110 $self->{phonenum} = shift if @_;
116 Takes any number of call detail records (as L<FS::cdr> objects),
117 formats them, and appends them to the internal buffer.
119 By default, this simply calls C<single_detail> on each CDR in the
120 set. Subclasses should override C<append> and maybe C<finish> if
121 they do not produce detail lines from CDRs in a 1:1 fashion.
123 The 'billpkgnum', 'invnum', 'pkgnum', and 'phonenum' fields will
131 push @{ $self->{buffer} }, $self->single_detail($_);
137 Returns all invoice detail records in the buffer. This will perform
138 a C<finish> first. Subclasses generally shouldn't override this.
150 Ensures that all invoice details are generated given the CDRs that
151 have been appended. By default, this does nothing.
159 Returns a header row for the format, as an L<FS::cust_bill_pkg_detail>
160 object. By default this has 'format' = 'C', 'detail' = the value
161 returned by C<header_detail>, and all other fields empty.
163 This is called after C<finish>, so it can use information from the CDRs.
170 FS::cust_bill_pkg_detail->new(
171 { 'format' => 'C', 'detail' => $self->mt($self->header_detail) }
175 =item single_detail CDR
177 Takes a single CDR and returns an invoice detail to describe it.
179 By default, this maps the following fields from the CDR:
181 rated_price => amount
182 rated_classnum => classnum
183 rated_seconds => duration
184 rated_regionname => regionname
185 accountcode => accountcode
186 startdate => startdate
188 'phonenum' is set to the internal C<phonenum> value set on the formatter
191 It then calls C<columns> on the CDR to obtain a list of detail
192 columns, formats them as a CSV string, and stores that in the
201 my @columns = $self->columns($cdr);
202 my $status = $self->csv->combine(@columns);
203 die "$me error combining ".$self->csv->error_input."\n"
206 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
207 my $price = $object->rated_price if $object;
208 $price = 0 if $cdr->freesidestatus eq 'no-charge';
210 FS::cust_bill_pkg_detail->new( {
212 'classnum' => $cdr->rated_classnum,
213 'duration' => $cdr->rated_seconds,
214 'regionname' => $cdr->rated_regionname,
215 'accountcode' => $cdr->accountcode,
216 'startdate' => $cdr->startdate,
218 'detail' => $self->csv->string,
219 'phonenum' => $self->phonenum,
225 Returns a list of CSV columns (to be shown on the invoice) for
226 the CDR. This is the method most subclasses should override.
232 die "$me no columns method in ".ref($self);
237 Returns the 'detail' field for the header row. This should
238 probably be a CSV string of column headers for the values returned
245 die "$me no header_detail method in ".ref($self);
248 # convenience methods for subclasses
250 sub conf { $_[0]->{conf} }
252 sub csv { $_[0]->{csv} }
256 $self->{date_format} ||= ($self->conf->config('date_format') || '%m/%d/%Y');
261 $self->{money_char} ||= ($self->conf->config('money_char') || '$');
264 # localization methods
268 $self->{_dh}->time2str(@_);
273 $self->{_lh}->maketext(@_);
276 #imitate previous behavior for now
281 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
282 my $sec = $object->rated_seconds if $object;
284 # XXX termination objects don't have rated_granularity so this may
285 # result in inbound CDRs being displayed as min/sec when they shouldn't.
286 # Should probably fix this.
287 if ( $cdr->rated_granularity eq '0' ) {
290 elsif ( $cdr->rated_granularity eq '60' ) {
291 sprintf('%dm', ($sec + 59)/60);
294 sprintf('%dm %ds', $sec / 60, $sec % 60);
301 my $object = $self->{inbound} ? $cdr->cdr_termination(1) : $cdr;
302 my $price = $object->rated_price if $object;
303 $price = '0.00' if $object->freesidestatus eq 'no-charge';
304 length($price) ? $self->money_char . $price : '';