\*(C'\fR,
\&\f(CW\*(C`| \*(C'\fR, and \f(CW\*(C` | \*(C'\fR tags).
.IP "\(bu" 4
Options to generate \*(L"striped reports\*(R" (i.e. tables, where the formatting
is dependent on the row\- or column-index).
.IP "\(bu" 4
Options which are only applied when a data-dependent condition is fulfilled.
.PP
The last group is more complicated, because not only do the actual formatting
options have to be set, but also the \*(L"trigger\*(R" and the range of table cells
to which it is supposed to be applied.
.PP
Formatting options can be set using three different ways:
.IP "1." 4
Single argument: e.g. \f(CW\*(C`$dash\->set_table( "border=\*(Aq1\*(Aq" )\*(C'\fR or
\&\f(CW\*(C`$dash\->set_first_row( \*(Aqred\*(Aq )\*(C'\fR.
.IP "2." 4
As explicit \s-1CSS\s0 style directive: e.g.
\&\f(CW\*(C`$dash\->set_th( style => \*(Aqfont\-size: x\-large\*(Aq )\*(C'\fR or
\&\f(CW\*(C`$dash\->set_even_row( style => \*(Aqbackground\-color: yellow\*(Aq )\*(C'\fR.
.IP "3." 4
By naming a \s-1CSS\s0 class: e.g.
\&\f(CW\*(C`$dash\->set_td( class => \*(Aqhighlighted\*(Aq )\*(C'\fR or
\&\f(CW\*(C`$dash\->set_even_col( class => \*(Aqevencol\*(Aq )\*(C'\fR. (Obviously, the
class set in this way should be defined in a stylesheet referenced
by the \s-1HTML\s0 page containing the dashboard.)
.PP
When using the \*(L"style\*(R" and \*(L"class\*(R" methods, a \*(L"style\*(R" or \*(L"class\*(R"
argument is included into the appropriate \s-1HTML\s0 tags, and set to the
supplied value. Note that repeated calls to these functions are
additive, \fInot\fR exclusive. In other words, the following two code
samples are equivalent:
.PP
.Vb 2
\& $dash\->set_even_row( style => \*(Aqbackground\-color: yellow\*(Aq );
\& $dash\->set_even_row( style => \*(Aqfont\-size: x\-large\*(Aq );
.Ve
.PP
is equivalent to:
.PP
.Vb 1
\& $dash\->set_even_row( style => \*(Aqbackground\-color: yellow; font\-size: x\-large\*(Aq );
.Ve
.PP
(The module will supply semicolons between different style directives
when merging the results from repeated calls.)
.PP
To erase previous style directives, assign \f(CW\*(C`undef\*(C'\fR explicitly:
\&\f(CW\*(C`$dash\->set_even_row( style => undef )\*(C'\fR.
.PP
The single-argument version is intended as a short-cut and has a
slightly different meaning, depending on the group of formatting
option it is applied to. When applied to a direct \s-1HTML\s0 option (i.e.
when used with \f(CW\*(C`set_table()\*(C'\fR, \f(CW\*(C`set_tr()\*(C'\fR, \f(CW\*(C`set_th()\*(C'\fR, or \f(CW\*(C`set_td()\*(C'\fR),
the argument is pasted unmodified into the corresponding \s-1HTML\s0 tag.
When used with any other option, the argument is interpreted as the
\&\fIdesired background color\fR for the cell, row, or column. The specified
background color will be applied as an explicit \*(L"style\*(R" argument, \fInot\fR
as a \*(L"bgcolor\*(R" argument. In other words, the following calls are (almost)
equivalent:
.PP
.Vb 2
\& $dash\->set_first_row( \*(Aqcyan\*(Aq );
\& $dash\->set_first_row( style => \*(Aqbackground\-color: cyan\*(Aq );
.Ve
.PP
It is legal to set conflicting formatting options and will not prevent
generation of \s-1HTML\s0 output. However, no guarantees are made about the
appearance of the dashboard in the browser in this case.
.PP
\&\fBIn the following, \f(CB\*(C`[format]\*(C'\fB always stand for formatting
options in any one of the three legal syntax variants as discussed above!\fR
.PP
\fIGeneral \s-1HTML\s0 Options\fR
.IX Subsection "General HTML Options"
.ie n .IP "$dash\->set_table( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_table( \f(CW[format]\fR )" 4
.IX Item "$dash->set_table( [format] )"
.PD 0
.ie n .IP "$dash\->set_tr( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_tr( \f(CW[format]\fR )" 4
.IX Item "$dash->set_tr( [format] )"
.ie n .IP "$dash\->set_th( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_th( \f(CW[format]\fR )" 4
.IX Item "$dash->set_th( [format] )"
.ie n .IP "$dash\->set_td( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_td( \f(CW[format]\fR )" 4
.IX Item "$dash->set_td( [format] )"
.ie n .IP "$hash_ref = $dash\->\fIget_table()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_table()\fR" 4
.IX Item "$hash_ref = $dash->get_table()"
.ie n .IP "$hash_ref = $dash\->\fIget_tr()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_tr()\fR" 4
.IX Item "$hash_ref = $dash->get_tr()"
.ie n .IP "$hash_ref = $dash\->\fIget_th()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_th()\fR" 4
.IX Item "$hash_ref = $dash->get_th()"
.ie n .IP "$hash_ref = $dash\->\fIget_td()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_td()\fR" 4
.IX Item "$hash_ref = $dash->get_td()"
.PD
If set, these options are always included into all tags. This is mostly
useful to style the entire table, or cells in the header row.
.PP
\fIStriped Reports\fR
.IX Subsection "Striped Reports"
.ie n .IP "$dash\->set_first_row( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_first_row( \f(CW[format]\fR )" 4
.IX Item "$dash->set_first_row( [format] )"
.PD 0
.ie n .IP "$dash\->set_odd_row( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_odd_row( \f(CW[format]\fR )" 4
.IX Item "$dash->set_odd_row( [format] )"
.ie n .IP "$dash\->set_even_row( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_even_row( \f(CW[format]\fR )" 4
.IX Item "$dash->set_even_row( [format] )"
.ie n .IP "$dash\->set_last_row( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_last_row( \f(CW[format]\fR )" 4
.IX Item "$dash->set_last_row( [format] )"
.ie n .IP "$hash_ref = $dash\->\fIget_first_row()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_first_row()\fR" 4
.IX Item "$hash_ref = $dash->get_first_row()"
.ie n .IP "$hash_ref = $dash\->\fIget_odd_row()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_odd_row()\fR" 4
.IX Item "$hash_ref = $dash->get_odd_row()"
.ie n .IP "$hash_ref = $dash\->\fIget_even_row()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_even_row()\fR" 4
.IX Item "$hash_ref = $dash->get_even_row()"
.ie n .IP "$hash_ref = $dash\->\fIget_last_row()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_last_row()\fR" 4
.IX Item "$hash_ref = $dash->get_last_row()"
.ie n .IP "$dash\->set_first_col( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_first_col( \f(CW[format]\fR )" 4
.IX Item "$dash->set_first_col( [format] )"
.ie n .IP "$dash\->set_odd_col( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_odd_col( \f(CW[format]\fR )" 4
.IX Item "$dash->set_odd_col( [format] )"
.ie n .IP "$dash\->set_even_col( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_even_col( \f(CW[format]\fR )" 4
.IX Item "$dash->set_even_col( [format] )"
.ie n .IP "$dash\->set_last_col( ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_last_col( \f(CW[format]\fR )" 4
.IX Item "$dash->set_last_col( [format] )"
.ie n .IP "$hash_ref = $dash\->\fIget_first_col()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_first_col()\fR" 4
.IX Item "$hash_ref = $dash->get_first_col()"
.ie n .IP "$hash_ref = $dash\->\fIget_odd_col()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_odd_col()\fR" 4
.IX Item "$hash_ref = $dash->get_odd_col()"
.ie n .IP "$hash_ref = $dash\->\fIget_even_col()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_even_col()\fR" 4
.IX Item "$hash_ref = $dash->get_even_col()"
.ie n .IP "$hash_ref = $dash\->\fIget_last_col()\fR" 4
.el .IP "\f(CW$hash_ref\fR = \f(CW$dash\fR\->\fIget_last_col()\fR" 4
.IX Item "$hash_ref = $dash->get_last_col()"
.PD
Options set with these functions are applied to rows or columns as
appropriate. Note that first, last, even, and odd is understood with
reference to the page or the view, \fInot\fR the total data set.
.Sp
Options for first and last prevail over options for even and odd.
Options for columns prevail over options for rows.
.PP
\fIConditional Formatting (Triggers)\fR
.IX Subsection "Conditional Formatting (Triggers)"
.PP
Formatting options in this group are only applied if a \*(L"trigger\*(R"
evaluates to true. Therefore, the functions below all take a function
reference as argument, besides the actual formatting options.
.PP
All triggers have a \*(L"priority\*(R" from highest (hi), over intermediate (med)
to lowest (low). If multiple triggers evaluate to true for a certain part
of the dashboard (say, a cell), then only the formatting option with the
highest priority is applied.
.PP
The intended application is to show whether a set of data is \*(L"in the
green\*(R" or \*(L"in the red\*(R". Given the prioritization logic of the triggers,
this can be easily achieved, without the need for exclusive bounds or
conditions across the set of triggers, using code like this:
.PP
.Vb 3
\& $dash\->set_row_low( sub{ ...; $x < 3 }, \*(Aqgreen\*(Aq );
\& $dash\->set_row_med( sub{ ...; $x < 7 }, \*(Aqyellow\*(Aq );
\& $dash\->set_row_hi( sub{ ...; $x > 10 }, \*(Aqred\*(Aq );
.Ve
.ie n .IP "$dash\->set_row_hi( sub{ my ( $row_ref ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_row_hi( sub{ my ( \f(CW$row_ref\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_row_hi( sub{ my ( $row_ref ) = @_; ... }, [format] )"
.PD 0
.ie n .IP "$dash\->set_row_med( sub{ my ( $row_ref ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_row_med( sub{ my ( \f(CW$row_ref\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_row_med( sub{ my ( $row_ref ) = @_; ... }, [format] )"
.ie n .IP "$dash\->set_row_low( sub{ my ( $row_ref ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_row_low( sub{ my ( \f(CW$row_ref\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_row_low( sub{ my ( $row_ref ) = @_; ... }, [format] )"
.PD
If the triggers evaluates to true, the formatting option is applied
to the entire row. The argument to the trigger is an array-ref to
the current row. (Additional arguments: index of row in page, and
index of row in data set.)
.ie n .IP "$dash\->set_col_hi( $col, sub{ my ( $cell ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_col_hi( \f(CW$col\fR, sub{ my ( \f(CW$cell\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_col_hi( $col, sub{ my ( $cell ) = @_; ... }, [format] )"
.PD 0
.ie n .IP "$dash\->set_col_med( $col, sub{ my ( $cell ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_col_med( \f(CW$col\fR, sub{ my ( \f(CW$cell\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_col_med( $col, sub{ my ( $cell ) = @_; ... }, [format] )"
.ie n .IP "$dash\->set_col_low( $col, sub{ my ( $cell ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_col_low( \f(CW$col\fR, sub{ my ( \f(CW$cell\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_col_low( $col, sub{ my ( $cell ) = @_; ... }, [format] )"
.PD
The first argument to this function is the index of the column \fIin the
data set\fR (not in the view!) to which the formatting should be applied.
If the triggers evaluates to true, the formatting option is applied to
all cells in the column. The argument to the trigger is the contents of
the current cell in the specified column.(Additional arguments: the
index in the view and in the data set.)
.ie n .IP "$dash\->set_cell_hi( $col, sub{ my ( $cell ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_cell_hi( \f(CW$col\fR, sub{ my ( \f(CW$cell\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_cell_hi( $col, sub{ my ( $cell ) = @_; ... }, [format] )"
.PD 0
.ie n .IP "$dash\->set_cell_med( $col, sub{ my ( $cell ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_cell_med( \f(CW$col\fR, sub{ my ( \f(CW$cell\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_cell_med( $col, sub{ my ( $cell ) = @_; ... }, [format] )"
.ie n .IP "$dash\->set_cell_low( $col, sub{ my ( $cell ) = @_; ... }, ""[format]"" )" 4
.el .IP "\f(CW$dash\fR\->set_cell_low( \f(CW$col\fR, sub{ my ( \f(CW$cell\fR ) = \f(CW@_\fR; ... }, \f(CW[format]\fR )" 4
.IX Item "$dash->set_cell_low( $col, sub{ my ( $cell ) = @_; ... }, [format] )"
.PD
The first argument to this function is the index of the column \fIin the
data set\fR (not in the view!) to which the formatting should be applied.
If the triggers evaluates to true, the formatting option is applied to
the current cell only. The argument to the trigger is the contents of
the current cell in the specified column.(Additional arguments: the
index in the view and in the data set.)
.PP
Options set with triggers are \fImerged\fR (do not clobber) with options set
for first/last and even/odd. (This allows one to have a striped report, and
use triggers to change the text color only.)
.PP
Options with high (hi) priority prevail over (clobber) options with
intermediate (med) priority, which prevail over options with low priority.
Options for cells prevail over options for columns, which prevail over
options for rows.
.SS "Content Formatters"
.IX Subsection "Content Formatters"
.ie n .IP "$dash\->set_format( $column, sub { ... } )" 4
.el .IP "\f(CW$dash\fR\->set_format( \f(CW$column\fR, sub { ... } )" 4
.IX Item "$dash->set_format( $column, sub { ... } )"
.PD 0
.ie n .IP "$dash\->set_collate( $column, sub { ... } )" 4
.el .IP "\f(CW$dash\fR\->set_collate( \f(CW$column\fR, sub { ... } )" 4
.IX Item "$dash->set_collate( $column, sub { ... } )"
.PD
If set, the registered function is called for each row. Its output
is used as contents for the current row's cell in the column with
index \f(CW$column\fR.
.Sp
A formatter set with the first function is given the contents of
the data in the current cell, while a collater set with the second
function is given the entire row (as array).
.Sp
Examples:
.Sp
.Vb 2
\& $dash\->set_format( 1, sub { my ( $x ) = @_; sprintf( "%.2f", $x ) } )
\& $dash\->set_collate( 1, sub { my ( $r ) = @_; $r[1] . \*(Aq:\*(Aq . $r[2] } )
.Ve
.SH "RATIONALE"
.IX Header "RATIONALE"
It was important to me to define a module that would be easy to use,
with reasonable defaults and a reasonably small \s-1API.\s0
.PP
In particular, I wanted a solution which would free the user entirely
from having to deal with (i.e. explicitly loop over) individual rows
and cells. Furthermore, the user should not have to specify information
that is already present in the data (such as the number of rows and
columns). Finally, I wanted to free the user from having to address
individual cells (e.g. by their location) to provide formatting
instructions.
.PP
All this required a rule-based system \-\-\- you specify the high-level
rules, the module makes sure they are applied as necessary.
.PP
Below are some further questions that have been asked \-\-\- with answers:
.PP
Why not just use \s-1CSS\s0? Answer: All of this \fIis\fR done through \s-1CSS.\s0 The
difficulty is deciding to which cells to apply the \s-1CSS\s0 style directives
(if this is to be done in a data dependent manner). This module does
just that, by inserting the correct \s-1CSS \s0\*(L"class\*(R" arguments into the
appropriate cell tags (etc).
.PP
Why not go with a templating solution? Answer: Templates establish the
layout of a table from the outset, which makes it hard to do
cell-content-dependent formatting from within the template. And it is
simply not convenient, and not in the spirit of the thing, to build
templates with lots of conditional code in the template. (I know, having
used eg. \f(CW\*(C`HTML::Template\*(C'\fR quite extensively.) Given the data-dependent
nature of the problem, the table must be built-up row by row and cell
by cell individually, applying triggers and formatters as we go along.
This is what this module does \-\-\- and since we are already must touch
each cell individually, we might as well print its \s-1HTML\s0 as we go along.
Using templates in the implementation would not help.
.PP
Why not use Excel, \s-1PDF,\s0 or what have you? Because I want to deliver
my reports via the web, so I specifically want \s-1HTML\s0 output. (Duh!)
.PP
Why the name? Because I wanted something more specific and tangible
than \*(L"FormattedReport\*(R" or some such. The name points to the source
of the idea for this module: corporate metrics dashboards. What
managers want to see are the key metrics of the business (sales,
orders, what-have-you), with outliers highlighted to make it easy
to see which metrics are \*(L"in the green\*(R" and which are \*(L"in the red\*(R".
This module allows you to do just that. (And more.)
.SH "TO DO"
.IX Header "TO DO"
Several ideas:
.IP "\(bu" 4
Instead of setting the actual data, it would be nice to set merely a
query (and a \s-1DB\s0 handle) and let the dashboard pull its own data from
the \s-1DB.\s0
.IP "\(bu" 4
When there are subsequent rows, which have identical entries in some
columns it can be neat to suppress (leave blank) the repeated entries
(e.g. \f(CW\*(C`set_skip_repeats( @skip_cols )\*(C'\fR and \f(CW\*(C`get_skip_repeats()\*(C'\fR).
.IP "\(bu" 4
When setting data using an array-ref, it would be nice to specify an
optional integer parameter \f(CW$extend_by\fR, which would extend the range
of accessible columns. These new columns would be empty, but could be
used with \f(CW\*(C`set_collate()\*(C'\fR to build new column values on the fly. (This
is never necessary when using a \s-1DB\s0 query, since one can always include
constants in the \f(CW\*(C`SELECT\*(C'\fR clause.)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
I maintain a \*(L"gallery\*(R" of examples (with code) on my website at:
http://www.beyondcode.org/projects/dashboard/gallery.html
.PP
The module HTML::Tabulate seems close in intent to the present
module and may be an alternative. (The \s-1API\s0 is much larger than the
one for the present module and I am not entirely sure how it works.)
.PP
Several modules provide very thin wrappers around the actual
\&\s-1HTML\s0 of a table, they include HTML::Table, HTML::EasyTable,
HTML::ElementTable.
.PP
To generate tables directly from \s-1SQL\s0 queries, check out
Class::DBI::Plugin::FilterOnClick.
.SH "AUTHOR"
.IX Header "AUTHOR"
Philipp K. Janert, , http://www.beyondcode.org
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007 by Philipp K. Janert
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.8 or,
at your option, any later version of Perl 5 you may have available.
|