NAME
WWW::Analytics::MultiTouch::Tabular - Provides various output formats for writing tabular reports
SYNOPSIS
# 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 ],
);DESCRIPTION
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.
METHODS
new
$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
$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 ], ]header_layout, footer_layout
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.
txt
$output->txt(\@reports);Generate output in plain text format.
csv
$output->csv(\@reports);Generate output in CSV format.
xls
$output->xls(\@reports);Generate output in Excel spreadsheet format.
open
$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.
format
$output->format('xls');Set/get format to be used in print. open must be called for the format change to take effect.
filename
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
'outfile' is equivalent to 'filename', provided for backward compatibility.
filehandle
$output->filehandle(\*STDOUT);As an alternative to 'open', you can set the file handle explicitly using filehandle().
close
Close file
HEADERS AND FOOTERS
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
Optional column number. Will be placed at column 0 if not specified.
filename
Filename or URL of the image.
x_offset, y_offset
Optional pixel offsets of image from top-left of cell.
x_scale, y_scale
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".
row
Optional row number. Will be placed at the current row if not specified.
col
Optional column number. Will be placed at column 0 if not specified.
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 FORMAT
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'.
AUTHOR
Jon Schutz, <jon at jschutz.net>
BUGS
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.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc WWW::Analytics::MultiTouchYou 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
CPAN Ratings
Search CPAN
COPYRIGHT & LICENSE
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.