NAME

Apache::Wyrd::Chart - Embed Dynamically-redrawn PNG 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)

d 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
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>

LICENSE

See LICENSE under the documentation for Apache::Wyrd.

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