1BarGraph(3) User Contributed Perl Documentation BarGraph(3)
2
6 HTML::BarGraph - generate multiset bar graphs using plain HTML
7
9 use HTML::BarGraph;
10 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
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 Multiple customization options are provided, such as the maximum bar
61 length, bar colors etc.
62 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 direction
67 Default: "h". This arg indicates the orientation of the graphic
68 bars (horizontal, h or -, or vertical, v or |).
69 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 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 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 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 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 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 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 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 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 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 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 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 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 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 highlightcolor
156 Default: "red". This arg has effect only when "highlighttag" or
157 "highlightpos" has effect (see above).
158 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 showaxistags
165 Default: true. If true, "tags" are displayed along the base axis,
166 if provided.
167 showvalues
169 Default: true. If true, the values are displayed at the end of
170 each bar.
171 valuesuffix
173 If "showvalues" is true, any text string assigned to this argument
174 will be displayed after the max value.
175 valueprefix
177 If "showvalues" is true, any text string assigned to this argument
178 will be displayed before the max value.
179 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 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 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 bgcolor
200 Default: "white". This arg indicates the background color of the
201 graph area. See format of color args at "bordercolor".
202 textcolor
204 Default: "black". This arg indicates the font color of "tags" and
205 "values".
206 title
208 This arg indicates a string to be displayed as the title of the
209 graph.
210 titlecolor
212 Default: "textcolor". This arg only has effect when "title" is
213 specified, and indicates the font color of "title".
214 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 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 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 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 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 labeltextcolor
243 Default: "black". This arg indicates a color for the "xlabel" and
244 "ylabel" text.
245 labelbgcolor
247 Default: "bgcolor". This arg indicates a background color for the
248 row and column that contain the "xlabel" and "ylabel".
249
251 • alternate background color for dataset rows/cols
252 • accept a formatting string for max values (for sprintf)
254 • "showaxis"
256 • support same size bars: ######___ 66%
258 • ranges in tags, and "highlighttag"/"highlightpos" to fit in a range
260 • accept args to specify the text height for title, tags, max vals
262 • trick so that "ALT" attrib of "IMG" tags are displayed in
264 netscape/linux
265 • support for negative values (1 col/row for +, 1 col/row for -)
267 • implement an object oriented interface
269 • use HTML table building modules?
271 • test in IE
273
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 • values are not middle "valigned" for 'h'/'bgcolor' graphics
280
282 Vlad Podgurschi <cpan@podgurschi.org>
283
285 This library is free software; you can redistribute it and/or modify it
286 under the same terms as Perl itself.
287
289 perl(1).
290perl v5.38.0 2023-07-20 BarGraph(3)