HTML::BarGraph - generate multiset bar graphs using plain HTML
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', );
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.
HTML::BarGraph
width
height
img
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:
graph()
Default: h. This arg indicates the orientation of the graphic bars (horizontal, h or -, or vertical, v or |).
h
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.
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.
html
bgcolor
pixel
hight
Default: 100. This arg indicates the length of the bar (in pixels) for the maximum value to be represented in the graphic.
100
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).
barlength
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.
0.5
barwidth
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).
blue
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.
color
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.
htdocs
bartype
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.
lc()
colorname.png
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).
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.
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.
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.
tags
highlightpos
highlightcolor
highlighttag
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.
data
Default: red. This arg has effect only when highlighttag or highlightpos has effect (see above).
red
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.
addalt
Default: true. If true, tags are displayed along the base axis, if provided.
Default: true. If true, the values are displayed at the end of each bar.
If showvalues is true, any text string assigned to this argument will be displayed after the max value.
showvalues
If showvalues is true, any text string assigned to this argument will be displayed before the max value.
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).
undef
flat
borderwidth
bordercolor
<table>
reised
border
table
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.
black
bordertype
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.
3
1
Default: white. This arg indicates the background color of the graph area. See format of color args at bordercolor.
white
Default: black. This arg indicates the font color of tags and values.
values
This arg indicates a string to be displayed as the title of the graph.
Default: textcolor. This arg only has effect when title is specified, and indicates the font color of title.
textcolor
title
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.
center
left
right
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.
TimesRoman
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).
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.
xlabel
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.
middle
ylabel
top
bottom
Default: black. This arg indicates a color for the xlabel and ylabel text.
Default: bgcolor. This arg indicates a background color for the row and column that contain the xlabel and ylabel.
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
ALT
IMG
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
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
Vlad Podgurschi <cpan@podgurschi.org>
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl(1).
To install HTML::BarGraph, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTML::BarGraph
CPAN shell
perl -MCPAN -e shell install HTML::BarGraph
For more information on module installation, please visit the detailed CPAN module installation guide.