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,
64 and it accepts the following paramaters to define the graphic to be
65 drawn:
66 direction
68 Default: "h". This arg indicates the orientation of the graphic
69 bars (horizontal, h or -, or vertical, v or |).
70 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 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 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 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 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 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 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 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 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 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 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 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 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 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 highlightcolor
157 Default: "red". This arg has effect only when "highlighttag" or
158 "highlightpos" has effect (see above).
159 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 showaxistags
166 Default: true. If true, "tags" are displayed along the base axis,
167 if provided.
168 showvalues
170 Default: true. If true, the values are displayed at the end of
171 each bar.
172 valuesuffix
174 If "showvalues" is true, any text string assigned to this argument
175 will be displayed after the max value.
176 valueprefix
178 If "showvalues" is true, any text string assigned to this argument
179 will be displayed before the max value.
180 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 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 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 bgcolor
201 Default: "white". This arg indicates the background color of the
202 graph area. See format of color args at "bordercolor".
203 textcolor
205 Default: "black". This arg indicates the font color of "tags" and
206 "values".
207 title
209 This arg indicates a string to be displayed as the title of the
210 graph.
211 titlecolor
213 Default: "textcolor". This arg only has effect when "title" is
214 specified, and indicates the font color of "title".
215 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 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 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 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 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 labeltextcolor
244 Default: "black". This arg indicates a color for the "xlabel" and
245 "ylabel" text.
246 labelbgcolor
248 Default: "bgcolor". This arg indicates a background color for the
249 row and column that contain the "xlabel" and "ylabel".
250
252 · alternate background color for dataset rows/cols
253 · accept a formatting string for max values (for sprintf)
255 · "showaxis"
257 · support same size bars: ######___ 66%
259 · ranges in tags, and "highlighttag"/"highlightpos" to fit in a range
261 · accept args to specify the text height for title, tags, max vals
263 · trick so that "ALT" attrib of "IMG" tags are displayed in
265 netscape/linux
266 · support for negative values (1 col/row for +, 1 col/row for -)
268 · implement an object oriented interface
270 · use HTML table building modules?
272 · test in IE
274
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 · values are not middle "valigned" for 'h'/'bgcolor' graphics
281
283 Vlad Podgurschi <cpan@podgurschi.org>
284
286 This library is free software; you can redistribute it and/or modify it
287 under the same terms as Perl itself.
288
290 perl(1).
291perl v5.12.0 2002-12-06 BarGraph(3)