NAME

Apache::Wyrd::Chart - Embed Dynamically-redrawn charts in HTML

SYNOPSIS

  <BASENAME::Chart img="chart.png" type="bars" height="200" width="300">
    <BASENAME::Query>
      select month, price
      from monthly_prices
      order by month
    </BASENAME::Query>
  </BASENAME::Chart>

DESCRIPTION

Chart-graphic Wyrd wrapping the GD::Graph Module. Creates a graphic file (PNG) and a meta-data file based on data handed it to by an Apache::Wyrd::Query Wyrd.

HTML ATTRIBUTES

The Chart Wyrd accepts nearly all the attributes of the GD::Graph module and the <img> tag, producing an <img> tag which points to the graphic file produced by GD::Graph, having most attributes (such as onClick, border, but not src) given to the Chart Wyrd.

Wyrd attributes:

data_col

Which column of the query to plot. Default: 2.

labels

A comma or whitespace-separated list of label names. If not enough labels are given, the remainder will be labeled "unknown"

label_col

Which column of the query to use for labels. Default: 1.

other_limit

Items with values under this number will be lumped together under the item name "Other".

label_filters, value_filters

A whitespace or comma delineated list of builtin filters to apply to the labels or values respectively. Current filters:

zero

Replace undefined values with 0.

dollar_sign

Put a dollar sign to the left

percent_sign

Put a percent sign to the right

commify

Put numbers into (north american style) comma splits, i.e. 3,000,000 for 3E6

Flags

nochache

Always generate the graphic, instead of checking to see if it has changed

percent

Convert values to percentages of total

rotate

Pivot the table returned by the query to make X Y and vice-versa

value_labels

Add the value to the label, as in "Foobars (2), Widgets (23)"

IMG-style attributes:

height, width, vspace, border, hspace

In pixels, as per IMG tag

src

Required - Where (document-root-relative) the graphic is to appear. Currently must end with .png.

GD::Graph-style attributes

See GD::Graph documentation for more details. Files are always document-root-relative. Colors may be in GD::Graph name format or in in HTML "#XXXXXX" format. Edge-positions are in the GD::Graph standard of UL for Upper-Left, LL for Lower-Left, etc. 1 is the usual value for "yes" in boolean attributes. Lists are in a whitespace-separated or comma-separated list of items (using Apache::Wyrd::Services::SAK::token_parse). Angles are in degrees.

type

What type of graph, per the GD::Graph subclasses. Valid types are: lines, hbars, bars, points, linespoints, area, or pie

b_margin t_margin l_margin r_margin

edge-to-graphic margins

transparent interlaced

PNG options

bgclr fgclr boxclr textclr labelclr axislabelclr legendclr valuesclr accentclr shadowclr

Colors for the respective chart elements

dclrs borderclrs

Data element and border colors, in list format.

show_values values_vertical values_space values_format

Whether (1=yes) to show values, whether vertically, what space (pixels) around them and what (sprintf-style) format to display them in.

logo logo_position logo_resize

logo file, corner for logo, and resize factor

legend_placement legend_spacing legend_marker_width legend_marker_height lg_cols

Legend attributes (axestype graphs only)

x_label y_label box_axis two_axes zero_axis zero_axis_only x_plot_values y_plot_values y_max_value y_min_value x_tick_number x_min_value x_tick_number x_min_value x_max_value y_number_format x_label_skip y_label_skip x_tick_offset x_all_ticks x_label_position y_label_position x_labels_vertical long_ticks tick_length x_ticks y_tick_number axis_space text_space

Axis attributes (for applicable chart types)

overwrite bar_width bar_spacing shadow_depth borderclrs cycle_clrs cumulate

Bar-chart attributes, foo_clrs are lists. Cumulate is boolean, and means to stack values within a bar

line_types line_type_scale line_width skip_undef

Line-chart attributes. Line types are 1: solid, 2: dashed, 3: dotted, 4: dot-dashed. skip_undef leaves a gap for an undefined point

markers marker_size

Marker types (1: filled square, 2: open square, 3: horizontal cross, 4: diagonal cross, 5: filled diamond, 6: open diamond, 7: filled circle, 8: open circle, 9: horizontal line, 10: vertical line) and size (in pixels)

3d pie_height start_angle suppress_angle

Pie chart attributes. suppress_angle is a limit below which no line is drawn

legend_font title_font x_label_font y_label_font x_axis_font y_axis_font

Fonts. Either a file (if your system supports TTF) or one of the builtin fonts: gdTinyFont gdSmallFont gdMediumBoldFont gdLargeFont gdGiantFont

PERL METHODS

(format: (returns) name (arguments after self))

(void) _alter_graphic (GD Object)

"Hook" method for putting final changes on the plotted GD graphic. Accepts the graphic as a GD object. Does nothing by default.

(undef) _process_chart (GD::Graph Object)

"Hook" method for putting final changes on the GD::Graph object. Accepts the chart as a GD::Graph object. Does nothing by default.

(void) _set_default_attribs (void)

"Hook" method for setting default attributes. Does nothing by default.

(scalar) _special_filter (scalar, scalar)

"Hook" for filtering data/labels. Should accept a value for the filter and the data to perform filters upon.

BUGS/CAVEATS/RESERVED METHODS

Reserves the register_filter, _setup and _format_output methods. Also reserves the methods _set_default_attributes, _get_data, _process_data, _filter_labels, _filter_values, _filter. Also reserves the standard register_query method.

Produces, by default, a second file (<graphic_name>.tdf) in the same directory as the graphic which has the HTML fingerprint and the data stored in tab-delineated-text format.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

LICENSE

Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.