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

TODO

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

BUGS

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

AUTHOR

282       Vlad Podgurschi  <cpan@podgurschi.org>
283

LICENSE

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

SEE ALSO

289       perl(1).
290
291
292
293perl v5.36.0                      2023-01-20                       BarGraph(3)
Impressum