WWW::Analytics::MultiTouch::Tabular - Provides various output formats for writing tabular reports
# Simple usage
use WWW::Analytics::MultiTouch::Tabular; my @data = ( [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ], ); my @reports = ( { title => "Number of Results in Top 10, by Site", sheetname => "Top Positions", headings => [ "Site", "Engine", "Top 10 Results", "Unique URLs", "Top 10 Previous Week", "Unique URLs Previous Week" ], data => \@data, }, ... ); my $output = WWW::Analytics::MultiTouch::Tabular->new({format => 'txt', outfile => $file}); $output->print(\@reports); $output->close();
# With formatting
my @data = ( [ [ 1, { color => 'red' } ], 2, 3 ], [ [ 4, { color => '#123456' ], 5, 6 ], [ [ 7, { bold => 1 } ], 8, 9 ], );
Takes a list of reports and outputs them in the specified format (text, csv, or Excel).
For Excel, supports extended formatting including headers, footers, colours, fonts, images, charts.
$output = WWW::Analytics::MultiTouch::Tabular->new({format => 'txt', filename => $file});
Creates a new WWW::Analytics::MultiTouch::Tabular object. Options are as follows:
format
txt, csv or xls.
filename
Name of output file
header_layout, footer_layout
See "HEADERS AND FOOTERS".
$output->print(\@reports);
Prints given data in txt, csv, or xls format.
Each item in @reports is a hash containing the following elements:
title
Report title
sheetname
Sheet name, where applicable (as in spreadsheet output).
headings
Array of column headings. Each heading entry may be a scalar (used as is) or a two-element array, in which case the first element is the data and the second element is the cell format. See "CELL FORMAT" for cell formatting details.
data
Array of data; each row is a row in the output, with columns corresponding to the column headings given. Each data point may be a scalar (used as is) or a two-element array, in which case the first element is the data and the second element is the cell format. See "CELL FORMAT" for cell formatting details.
Examples:
Simple data array, no formatting:
data => [ [ 1, 2, 3 ], [ 4, 5, 6 ], [ 7, 8, 9 ], ]
Data array with first entry in each row formatted:
data => [ [ [ 1, { color => 'red' } ], 2, 3 ], [ [ 4, { color => '#123456' ], 5, 6 ], [ [ 7, { bold => 1 } ], 8, 9 ], ]
chart
Insert one or more charts. Example:
chart => [ { type => 'column', x_scale => 1.5, y_scale => 1.5, series => [ map { { categories => [ -1, -1, 1, scalar @{$data[0]} ], values => [ $_, $_, 1, scalar @{$data[0]} ], name_formula => [$_, 0], name => $data[$_][0], } } (0 .. @data - 1) ] } ],
Options are:
type
May be 'area', 'bar', 'column', 'line', 'pie', 'scatter', 'stock'. See Spreadsheet::WriteExcel::Chart for more details on the available types.
series
This is the array of data series for the chart. 'categories', 'values' and 'name_formula' are given in terms of cell ranges referenced to the start of the spreadsheet data. The heading row may be referenced as -1 relative to the start of the data. See "add_series" in Spreadsheet::WriteExcel::Chart for more details.
row, abs_row
Optional row offset or absolute row position. Will be placed at the current row if not specified.
col, abs_col
Optional column number. Will be placed at column 0 if not specified.
x_scale, y_scale
Optional chart scaling factors.
title, x_axis, y_axis, legend, chartarea, plotarea
See the corresponding set_* method in Spreadsheet::WriteExcel::Chart for more details.
$output->txt(\@reports);
Generate output in plain text format.
$output->csv(\@reports);
Generate output in CSV format.
$output->xls(\@reports);
Generate output in Excel spreadsheet format.
$output->format('csv'); $output->filename("$dir/csv-test.csv"); $output->open; $output->open("xls", "$dir/xls-test.xls");
'open' opens a file for writing. It is usually not necessary to call 'open' as it is implicit in 'new'. However, if you wish to re-use the object created with 'new' to output a different format or to a different file, then you need to call open with the new format/file arguments, or after setting the new format and output file with the format and outfile methods.
$output->format('xls');
Set/get format to be used in print. open must be called for the format change to take effect.
Set/get filename to be used in print. open must be called for the filename change to take effect.
If no filename is provided as an argument or previously set, STDOUT will be used.
'outfile' is equivalent to 'filename', provided for backward compatibility.
$output->filehandle(\*STDOUT);
As an alternative to 'open', you can set the file handle explicitly using filehandle().
Close file
A set of images, rows of text and/or spreadsheet operations to create page headers and footers. 'header_layout' is used prior to placing any data on the page, and 'footer_layout' afterwards. Example:
'header_layout' => { 'hide_gridlines' => '2', 'image' => [ { 'filename' => 'http://www.multitouchanalytics.com/images/multitouch-analytics-header.jpg', 'col' => 0, 'row' => 1, 'x_scale' => 0.7, 'y_scale' => 0.7 }, ], 'header' => [ { 'colspan' => '5', 'cell_format' => { 'color' => 'white', 'align' => 'center', 'bold' => 1, 'bg_color' => 'blue', 'size' => '16' }, 'text' => 'Multi Touch Reporting', 'col' => 0, 'row' => '5' }, { 'cell_format' => { 'align' => 'right', 'bold' => 1 }, 'text' => [ 'Generation Date:', 'Report Type:', 'Date Range:', 'Analysis Window:' ], 'col' => 0, 'row' => '7' }, { 'text' => [ '@generation_date', '@title', '@start_date - @end_date', '@window_length days' ], 'col' => 1, 'row' => '7' } ], 'start_row' => '10' } }
Options are as follows:
image
Specifies an image (PNG or JPEG) or images to be placed into the spreadsheet. Multiple images may be inserted by specifying an array of option hashes, comprising the following keys:
row
Optional row number. Will be placed at the current row if not specified.
col
Filename or URL of the image.
x_offset, y_offset
Optional pixel offsets of image from top-left of cell.
Optional image scaling factors.
header, footer
Specifies formatted rows of text. 'header' is intended to be used for 'header_layout' and 'footer' for 'footer_layout', but it doesn't actually matter if they are used the other way around. Multiple rows may be inserted by specifying an array of option hashes, comprising the following keys:
cell_format
See "CELL FORMAT".
rowspan, colspan
Optional row and column spans for merged cells.
text
Lines of text. If given as an array, each line will be inserted on subsequent rows, keeping the same formatting options.
Variables may be specified in the text as @variable_name, and will be substituted. Valid variable names are the top level keys passed in the report hash to print().
Any worksheet or page setup method from Spreadsheet::WriteExcel
e.g. keep_leading_zeros, show_comments, set_first_sheet, set_tab_color, hide_gridlines, set_zoom, etc.
Any valid Spreadsheet::WriteExcel worksheet method will be invoked with the given values, i.e.
hide_gridlines => 1 print_area => [ 1, 2, 3, 4 ]
invokes $worksheet->hide_gridlines(1) and $worksheet->print_area(1, 2, 3, 4).
Cell formatting options are defined through a hashref of any text formatting options from Spreadsheet::WriteExcel; specifically, any of 'font', 'size', 'color', 'bold', 'italic', 'underline', 'font_strikeout', 'font_script', 'font_outline', 'font_shadow', 'num_format', 'locked', 'hidden', 'align', 'valign', 'rotation', 'text_wrap', 'test_justlast', 'center_across', 'indent', 'shrink', 'pattern', 'bg_color', 'fg_color', 'border', 'bottom', 'top', 'left', 'right', 'border_color', 'bottom_color', 'top_color', 'left_color', 'right_color'.
Jon Schutz, <jon at jschutz.net>
<jon at jschutz.net>
Please report any bugs or feature requests to bug-www-analytics-multitouch at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Analytics-MultiTouch. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-www-analytics-multitouch at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc WWW::Analytics::MultiTouch
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=WWW-Analytics-MultiTouch
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/WWW-Analytics-MultiTouch
CPAN Ratings
http://cpanratings.perl.org/d/WWW-Analytics-MultiTouch
Search CPAN
http://search.cpan.org/dist/WWW-Analytics-MultiTouch/
Copyright 2010 YourAmigo Ltd. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
To install WWW::Analytics::MultiTouch, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Analytics::MultiTouch
CPAN shell
perl -MCPAN -e shell install WWW::Analytics::MultiTouch
For more information on module installation, please visit the detailed CPAN module installation guide.