From Freeside
< Freeside:4:Documentation:Developer‎ | FS‎ | Report‎ | Table
Revision as of 07:44, 18 November 2015 by Jeremyd (talk | contribs) (Edit via perl MediaWiki framework (1.13))

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


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


 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,
   '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;



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.


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.


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.


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.


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

Month labels, in MM/YYYY format.
speriod, eperiod
Absolute start and end times of each month, in unix time format.
The values passed in as items, with any suppressed rows deleted.
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.




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 302:
=back without =over