1BarGraph(3)           User Contributed Perl Documentation          BarGraph(3)
2
3
4

NAME

6       HTML::BarGraph - generate multiset bar graphs using plain HTML
7

SYNOPSIS

9       use HTML::BarGraph;
10
11        print graph(
12                    direction           => 'h',        ###  or 'v' or '|' / '-'
13                    graphminsize        => 250,
14                    bartype             => 'pixel',    ###  or 'html'
15                    barlength           => 100,
16                    barwidth            => 10 ,
17                    baraspect           => .03,
18                    color               => 'blue',
19                    colors              => [ 'blue', 'red', 'lightblue' ],
20                    pixeldir            => '/images',
21                    pixelfmt            => 'PNG',
22                    data                => [
23                                             [ val11, val12, ... ],
24                                             [ val21, val22, ... ],
25                                           ],
26                    tags                =>   [  one,  two, ...   ],
27                    setspacer           => 0,
28                    highlighttag        => [ tag1... ], ###  or tag1 (one value)
29                       # OR
30                    highlightpos        => [ 5, ...],   ###  or 5 (one value)
31                    highlightcolor      => 'red',
32                    addalt              => 1,
33                    showaxistags        => 1,
34                    showvalues          => 1,
35                    valuesuffix         => '%',
36                    valueprefix         => '=> ',
37                    bordertype          => 'flat',     ### or 'reised'
38                    bordercolor         => '#333333',  ### or '#RRGGBB'
39                    borderwidth         => 1,
40                    bgcolor             => 'bisque',   ### or '#RRGGBB'
41                    textcolor           => 'black',    ### or '#RRGGBB'
42                    title               => 'title',
43                    titlecolor          => 'black',    ### or '#RRGGBB'
44                    titlealign          => 'center',   ### or 'left' or 'right'
45                    fontface            => 'sansserif',
46                    ylabel              => 'randoms',
47                    ylabelalign         => 'middle',   ### or 'top' or 'bottom'
48                    xlabel              => 'index',
49                    xlabelalign         => 'center',   ### or 'left' or 'right'
50                    labeltextcolor      => 'yellow',
51                    labelbgcolor        => 'black',
52                  );
53

DESCRIPTION

55       "HTML::BarGraph" is a module that creates graphics for one or more
56       datasets, using plain HTML and, optionally, one-pixel images, which are
57       stretched using the "width" and "height" attributes of the HTML "img"
58       tag.
59
60       Multiple customization options are provided, such as the maximum bar
61       length, bar colors etc.
62
63       The main subroutine, "graph()", returns the HTML code for a graphic,
64       and it accepts the following paramaters to define the graphic to be
65       drawn:
66
67       direction
68           Default: "h".  This arg indicates the orientation of the graphic
69           bars (horizontal, h or -, or vertical, v or |).
70
71       graphminsize
72           Optional arg to specify the minimum size of the graph in the
73           direction of bar length;  this can be used to get a consistent size
74           when multiple graphics are displayed.
75
76       bartype
77           Default: "html".  This arg indicates whether the color bars should
78           be build as HTML tables with a certain "width", "height" and
79           "bgcolor", or out of a pixel image (value "pixel") "stretched" with
80           the "width" and "hight" attributes of "img" tag.
81
82       barlength
83           Default: 100.  This arg indicates the length of the bar (in pixels)
84           for the maximum value to be represented in the graphic.
85
86       barwidth
87           This arg indicates the width of a graphic's bar.  If this arg is
88           missing, it is calculated based on "barlength" and "baraspect"
89           (using their default values if they are missing too).
90
91       baraspect
92           Default: 0.5.  This arg indicates the aspect between the graphic
93           bar's width and length.  If both "barwidth" and "baraspect" are
94           set, "barwidth" is used.
95
96       color
97           Default: "blue".  This arg indicates the default color to be used
98           in drawing the graphic's bars for a single dataset representation
99           (see also "colors").
100
101       colors
102           Default: "color".   This arg should be an arrayref to a list of
103           colors to be used in displaying the bars for multiple dataset
104           graphs. If this arg is missing, the bars for all datasets will be
105           displayed in color "color". If the number of colors is smaller then
106           the number of datasets to be represented, the values are
107           "recycled". See also the Note for "color" argument.
108
109       pixeldir
110           Optional argument to indicate the directory where the color pixel
111           files are located;  for web scripts, this will have to be relative
112           to the "htdocs" dir. This argument is ignored unless "bartype" is
113           set to "pixel".
114
115       pixelfmt
116           Default: PNG.  Optional argument to indicate the graphic format of
117           the color pixel files; the "lc()" of this argument's value is used
118           as pixel file's extension (eg for PNG files, pixel files will be
119           "colorname.png".  This argument is ignored unless "bartype" is set
120           to "pixel".
121
122       data
123           This is a required arg, and should contain the datasets to be
124           represented in the graphic.  It should be passed as arrayref of
125           scalars (one set) or arrayrefs (multiple sets).
126
127       tags
128           If this arg is present, it should indicate the tags that should be
129           used to identify the values in datasets. It should be an arrayref
130           to a list of scalars, with at least that many elements as the
131           number of elements in the largest dataset.
132
133       setspacer
134           Default: true.  If true, this arg indicate that a space should be
135           inserted to separate the consecutive representations of datasets,
136           for a cleaner view.  It is set to false on single set
137           representations.
138
139       highlighttag
140           This arg has effect only for a single dataset representation, and
141           only when "tags" is present as well (when dataset has no "tags",
142           see "highlightpos").  It can be an arrayref or scalar. If present,
143           its values are compared with "tags" values, and in case it matches
144           one exactly, the color of the correspondent bar will be set to
145           "highlightcolor" , if specified (see below).  If both
146           "highlighttag" and "highlightpos" are specified, "highlightpos" is
147           ignored.
148
149       highlightpos
150           This arg has effect only for a single dataset representation.  It
151           can be an arrayref or scalar. If present, the color of the
152           correspondent 1-indexed position(s)in "data" will be set to
153           "highlightcolor", if specified (see below).  If both "highlighttag"
154           and "highlightpos" are specified, "highlightpos" is ignored.
155
156       highlightcolor
157           Default: "red".   This arg has effect only when "highlighttag" or
158           "highlightpos" has effect (see above).
159
160       addalt
161           Default: true.   If true, the "addalt" attribute is added to the
162           HTML "img" tag, having as value the value that is represented on
163           the bar.
164
165       showaxistags
166           Default: true.  If true, "tags" are displayed along the base axis,
167           if provided.
168
169       showvalues
170           Default: true.   If true, the values are displayed at the end of
171           each bar.
172
173       valuesuffix
174           If "showvalues" is true, any text string assigned to this argument
175           will be displayed after the max value.
176
177       valueprefix
178           If "showvalues" is true, any text string assigned to this argument
179           will be displayed before the max value.
180
181       bordertype
182           Default: "undef".  This arg sets the type of border the whole graph
183           will be surrounded by.  Valid values are "flat" (a frame of
184           "borderwidth" width and "bordercolor" color will be drawn around
185           the graphic, using "<table>" on "<table>" technique) or
186           "reised" (the "border" attribute of the HTML "table" will be set to
187           "borderwidth" value) (see below).
188
189       bordercolor
190           Default: "black".  This arg has effect only when "bordertype" is
191           set to "flat", and it indicates the color for the graph's frame).
192           The value of this arg can be a "well-known" color name (ie white,
193           black etc) or the RGB value, as specified in the HTML spec.
194
195       borderwidth
196           Default: 3 for "bordertype" set to "flat", and 1 for "reised".
197           This arg has effect only when "bordertype" is set, and it indicates
198           the width of the graph's border, in pixels.
199
200       bgcolor
201           Default: "white".  This arg indicates the background color of the
202           graph area.  See format of color args at "bordercolor".
203
204       textcolor
205           Default: "black".  This arg indicates the font color of "tags" and
206           "values".
207
208       title
209           This arg indicates a string to be displayed as the title of the
210           graph.
211
212       titlecolor
213           Default: "textcolor".  This arg only has effect when "title" is
214           specified, and indicates the font color of "title".
215
216       titlealign
217           Default: "center".  This arg only has effect when "title" is
218           specified, and it indicates the justification of the "title" on the
219           graph. Other valid values are "left" and "right".
220
221       fontface
222           Default: "TimesRoman".  This arg indicates the font face to be used
223           in the text displayed in the graph. The "title" is displayed using
224           size +2, the "tags" and axis labels (see below) in normal size, and
225           the max values at the head of graph bars in -1.
226
227       xlabel, ylabel
228           This args indicate the labels to be displayed on the base (x) and
229           values (y) axis of the graph.  Note: for a horizontal graph, the
230           names of the axes are reversed as normal (ie the x axis is the
231           vertical one).
232
233       xlabelalign
234           Default: "center".  This arg only has effect when a "xlabel" is
235           specified, and it indicates the justification of the "xlabel" on
236           the graph. Other valid values are "left" and "right".
237
238       ylabelalign
239           Default: "middle".  This arg only has effect when a "ylabel" is
240           specified, and it indicates the justification of the "ylabel" on
241           the graph. Other valid values are "top" and "bottom".
242
243       labeltextcolor
244           Default: "black".  This arg indicates a color for the "xlabel" and
245           "ylabel" text.
246
247       labelbgcolor
248           Default: "bgcolor".  This arg indicates a background color for the
249           row and column that contain the "xlabel" and "ylabel".
250

TODO

252       ·   alternate background color for dataset rows/cols
253
254       ·   accept a formatting string for max values (for sprintf)
255
256       ·   "showaxis"
257
258       ·   support same size bars:  ######___ 66%
259
260       ·   ranges in tags, and "highlighttag"/"highlightpos" to fit in a range
261
262       ·   accept args to specify the text height for title, tags, max vals
263
264       ·   trick so that "ALT" attrib of "IMG" tags are displayed in
265           netscape/linux
266
267       ·   support for negative values (1 col/row for +, 1 col/row for -)
268
269       ·   implement an object oriented interface
270
271       ·   use HTML table building modules?
272
273       ·   test in IE
274

BUGS

276       ·   in several cases, the bars are not perfectly aligned (left for 'h'
277           and bottom for 'v') and the values are written on the next line for
278           'h' graphics
279
280       ·   values are not middle "valigned" for 'h'/'bgcolor' graphics
281

AUTHOR

283       Vlad Podgurschi  <cpan@podgurschi.org>
284

LICENSE

286       This library is free software; you can redistribute it and/or modify it
287       under the same terms as Perl itself.
288

SEE ALSO

290       perl(1).
291
292
293
294perl v5.12.0                      2002-12-06                       BarGraph(3)
Impressum