BarGraph(3) User Contributed Perl Documentation BarGraph(3)NAMEHTML::BarGraph - generate multiset bar graphs using plain HTML
SYNOPSIS
use HTML::BarGraph;
print graph(
direction => 'h', ### or 'v' or '|' / '-'
graphminsize => 250,
bartype => 'pixel', ### or 'html'
barlength => 100,
barwidth => 10 ,
baraspect => .03,
color => 'blue',
colors => [ 'blue', 'red', 'lightblue' ],
pixeldir => '/images',
pixelfmt => 'PNG',
data => [
[ val11, val12, ... ],
[ val21, val22, ... ],
],
tags => [ one, two, ... ],
setspacer => 0,
highlighttag => [ tag1... ], ### or tag1 (one value)
# OR
highlightpos => [ 5, ...], ### or 5 (one value)
highlightcolor => 'red',
addalt => 1,
showaxistags => 1,
showvalues => 1,
valuesuffix => '%',
valueprefix => '=> ',
bordertype => 'flat', ### or 'reised'
bordercolor => '#333333', ### or '#RRGGBB'
borderwidth => 1,
bgcolor => 'bisque', ### or '#RRGGBB'
textcolor => 'black', ### or '#RRGGBB'
title => 'title',
titlecolor => 'black', ### or '#RRGGBB'
titlealign => 'center', ### or 'left' or 'right'
fontface => 'sansserif',
ylabel => 'randoms',
ylabelalign => 'middle', ### or 'top' or 'bottom'
xlabel => 'index',
xlabelalign => 'center', ### or 'left' or 'right'
labeltextcolor => 'yellow',
labelbgcolor => 'black',
);
DESCRIPTION
"HTML::BarGraph" is a module that creates graphics for one or more
datasets, using plain HTML and, optionally, one-pixel images, which are
stretched using the "width" and "height" attributes of the HTML "img"
tag.
Multiple customization options are provided, such as the maximum bar
length, bar colors etc.
The main subroutine, "graph()", returns the HTML code for a graphic,
and it accepts the following paramaters to define the graphic to be
drawn:
direction
Default: "h". This arg indicates the orientation of the graphic
bars (horizontal, h or -, or vertical, v or |).
graphminsize
Optional arg to specify the minimum size of the graph in the
direction of bar length; this can be used to get a consistent size
when multiple graphics are displayed.
bartype
Default: "html". This arg indicates whether the color bars should
be build as HTML tables with a certain "width", "height" and
"bgcolor", or out of a pixel image (value "pixel") "stretched" with
the "width" and "hight" attributes of "img" tag.
barlength
Default: 100. This arg indicates the length of the bar (in pixels)
for the maximum value to be represented in the graphic.
barwidth
This arg indicates the width of a graphic's bar. If this arg is
missing, it is calculated based on "barlength" and "baraspect"
(using their default values if they are missing too).
baraspect
Default: 0.5. This arg indicates the aspect between the graphic
bar's width and length. If both "barwidth" and "baraspect" are
set, "barwidth" is used.
color
Default: "blue". This arg indicates the default color to be used
in drawing the graphic's bars for a single dataset representation
(see also "colors").
colors
Default: "color". This arg should be an arrayref to a list of
colors to be used in displaying the bars for multiple dataset
graphs. If this arg is missing, the bars for all datasets will be
displayed in color "color". If the number of colors is smaller then
the number of datasets to be represented, the values are
"recycled". See also the Note for "color" argument.
pixeldir
Optional argument to indicate the directory where the color pixel
files are located; for web scripts, this will have to be relative
to the "htdocs" dir. This argument is ignored unless "bartype" is
set to "pixel".
pixelfmt
Default: PNG. Optional argument to indicate the graphic format of
the color pixel files; the "lc()" of this argument's value is used
as pixel file's extension (eg for PNG files, pixel files will be
"colorname.png". This argument is ignored unless "bartype" is set
to "pixel".
data
This is a required arg, and should contain the datasets to be
represented in the graphic. It should be passed as arrayref of
scalars (one set) or arrayrefs (multiple sets).
tags
If this arg is present, it should indicate the tags that should be
used to identify the values in datasets. It should be an arrayref
to a list of scalars, with at least that many elements as the
number of elements in the largest dataset.
setspacer
Default: true. If true, this arg indicate that a space should be
inserted to separate the consecutive representations of datasets,
for a cleaner view. It is set to false on single set
representations.
highlighttag
This arg has effect only for a single dataset representation, and
only when "tags" is present as well (when dataset has no "tags",
see "highlightpos"). It can be an arrayref or scalar. If present,
its values are compared with "tags" values, and in case it matches
one exactly, the color of the correspondent bar will be set to
"highlightcolor" , if specified (see below). If both
"highlighttag" and "highlightpos" are specified, "highlightpos" is
ignored.
highlightpos
This arg has effect only for a single dataset representation. It
can be an arrayref or scalar. If present, the color of the
correspondent 1-indexed position(s)in "data" will be set to
"highlightcolor", if specified (see below). If both "highlighttag"
and "highlightpos" are specified, "highlightpos" is ignored.
highlightcolor
Default: "red". This arg has effect only when "highlighttag" or
"highlightpos" has effect (see above).
addalt
Default: true. If true, the "addalt" attribute is added to the
HTML "img" tag, having as value the value that is represented on
the bar.
showaxistags
Default: true. If true, "tags" are displayed along the base axis,
if provided.
showvalues
Default: true. If true, the values are displayed at the end of
each bar.
valuesuffix
If "showvalues" is true, any text string assigned to this argument
will be displayed after the max value.
valueprefix
If "showvalues" is true, any text string assigned to this argument
will be displayed before the max value.
bordertype
Default: "undef". This arg sets the type of border the whole graph
will be surrounded by. Valid values are "flat" (a frame of
"borderwidth" width and "bordercolor" color will be drawn around
the graphic, using "<table>" on "<table>" technique) or
"reised" (the "border" attribute of the HTML "table" will be set to
"borderwidth" value) (see below).
bordercolor
Default: "black". This arg has effect only when "bordertype" is
set to "flat", and it indicates the color for the graph's frame).
The value of this arg can be a "well-known" color name (ie white,
black etc) or the RGB value, as specified in the HTML spec.
borderwidth
Default: 3 for "bordertype" set to "flat", and 1 for "reised".
This arg has effect only when "bordertype" is set, and it indicates
the width of the graph's border, in pixels.
bgcolor
Default: "white". This arg indicates the background color of the
graph area. See format of color args at "bordercolor".
textcolor
Default: "black". This arg indicates the font color of "tags" and
"values".
title
This arg indicates a string to be displayed as the title of the
graph.
titlecolor
Default: "textcolor". This arg only has effect when "title" is
specified, and indicates the font color of "title".
titlealign
Default: "center". This arg only has effect when "title" is
specified, and it indicates the justification of the "title" on the
graph. Other valid values are "left" and "right".
fontface
Default: "TimesRoman". This arg indicates the font face to be used
in the text displayed in the graph. The "title" is displayed using
size +2, the "tags" and axis labels (see below) in normal size, and
the max values at the head of graph bars in -1.
xlabel, ylabel
This args indicate the labels to be displayed on the base (x) and
values (y) axis of the graph. Note: for a horizontal graph, the
names of the axes are reversed as normal (ie the x axis is the
vertical one).
xlabelalign
Default: "center". This arg only has effect when a "xlabel" is
specified, and it indicates the justification of the "xlabel" on
the graph. Other valid values are "left" and "right".
ylabelalign
Default: "middle". This arg only has effect when a "ylabel" is
specified, and it indicates the justification of the "ylabel" on
the graph. Other valid values are "top" and "bottom".
labeltextcolor
Default: "black". This arg indicates a color for the "xlabel" and
"ylabel" text.
labelbgcolor
Default: "bgcolor". This arg indicates a background color for the
row and column that contain the "xlabel" and "ylabel".
TODO
· alternate background color for dataset rows/cols
· accept a formatting string for max values (for sprintf)
· "showaxis"
· support same size bars: ######___ 66%
· ranges in tags, and "highlighttag"/"highlightpos" to fit in a range
· accept args to specify the text height for title, tags, max vals
· trick so that "ALT" attrib of "IMG" tags are displayed in
netscape/linux
· support for negative values (1 col/row for +, 1 col/row for -)
· implement an object oriented interface
· use HTML table building modules?
· test in IE
BUGS
· in several cases, the bars are not perfectly aligned (left for 'h'
and bottom for 'v') and the values are written on the next line for
'h' graphics
· values are not middle "valigned" for 'h'/'bgcolor' graphics
AUTHOR
Vlad Podgurschi <cpan@podgurschi.org>
LICENSE
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSOperl(1).
perl v5.14.0 2002-12-06 BarGraph(3)
