Difference between revisions of "Freeside:3:Documentation:Developer/FS/Report/Table/Monthly"

Revision as of 05:54, 10 February 2015

NAME

FS::Report::Table::Monthly - Tables of report data, indexed monthly

SYNOPSIS

 use FS::Report::Table::Monthly;

 my $report = new FS::Report::Table::Monthly (
   'items' => [ 'invoiced', 'netsales', 'credits', 'receipts', ],
   'start_month' => 4,
   'start_year'  => 2000,
   'end_month'   => 4,
   'end_year'    => 2020,
   #opt
   'agentnum'    => 54
   'refnum'      => 54
   'cust_classnum' => [ 1,2,4 ],
   'params'      => [ [ 'paramsfor', 'item_one' ], [ 'item', 'two' ] ], # ...
   'remove_empty' => 1, #collapse empty rows, default 0
   'item_labels' => [ ], #useful with remove_empty
 );

 my $data = $report->data;

PARAMETERS

TIME PERIOD

start_month, start_year, end_month, and end_year specify the date range to be included in the report. The start and end months are included. Each month's values are summed from midnight on the first of the month to 23:59:59 on the last day of the month.

REPORT ITEMS

items: An arrayref of observables to calculate for each month. See FS::Report::Table for a list of observables and their parameters.; params: An arrayref, parallel to items, of arrayrefs of parameters (in paired name/value form) to be passed to the observables.; cross_params: Cross-product parameters. This must be an arrayref of arrayrefs of parameters (paired name/value form). This creates an additional "axis" (orthogonal to the time and items axes) in which the item is calculated once with each set of parameters in cross_params. These parameters are merged with those in params. Instead of being nested two levels, data will be nested three levels, with the third level corresponding to this arrayref.

FILTERING

agentnum: Limit to customers with this agent.; refnum: Limit to customers with this advertising source.; cust_classnum: Limit to customers with this classnum; can be an arrayref.; remove_empty: Set this to a true value to hide rows that contain only zeroes. The indices array in the returned data will list the item indices that are actually present in the output so that you know what they are. Ignored if cross_params is in effect.

PASS-THROUGH

item_labels, colors, and links may be specified as arrayrefs parallel to items. Those values will be returned in data, with any hidden rows (due to remove_empty) filtered out, which is the only reason to do this. Now that we have indices it's probably better to use that.

PROCESSING; normalize: Set this to an item index to have all other items expressed as a percentage of that one. That item will then be omitted from the output. If the normalization item is zero in some period, all the values in that period will be undef.

RETURNED DATA

The data method runs the report and returns a hashref of the following:

label

Month labels, in MM/YYYY format.

speriod, eperiod

Absolute start and end times of each month, in unix time format.

items

The values passed in as items, with any suppressed rows deleted.

indices

The indices of items in the input items list that appear in the result set. Useful for figuring out what they are when remove_empty has deleted some items.

item_labels, colors, links - see PASS-THROUGH above; data

The actual results. An arrayref corresponding to label (the time axis), containing arrayrefs corresponding to items, containing either numbers or, if cross_params is given, arrayrefs corresponding to cross_params.

BUGS

SEE ALSO

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 91:

'=item' outside of any '=over'

Around line 98:

You forgot a '=back' before '=head1'

Around line 296:

=back without =over