/ 
SVG-Sparkline-0.1.1
River stage zero No dependents
/ SVG::Sparkline

NAME

SVG::Sparkline - Create Sparklines in SVG

VERSION

This document describes SVG::Sparkline version 0.1.1

SYNOPSIS

  use SVG::Sparkline;

  my $sl1 = SVG::Sparkline->new( 'Whisker', { values=>\@values, color=>'#eee', height=>12 } );
  print $sl1->to_string();

  my $sl2 = SVG::Sparkline->new( 'Line', { y=>\@values, x=>\@x, color=>'blue', height=>12 } );
  print $sl2->to_string();

  my $sl3 = SVG::Sparkline->new( 'Area', { y=>\@values, x=>\@x, color=>'green', height=>10 } );
  print $sl3->to_string();

  my $sl4 = SVG::Sparkline->new( 'Bar', { values=>\@values, color=>'#66f', height=>10 } );
  print $sl4->to_string();

DESCRIPTION

In the book Beautiful Evidence, Edward Tufte describes sparklines as small, high-resolution, graphics embedded in a context of words, numbers, images.

This module provides a relatively easy interface for creating different kinds of sparklines. This class is not intended to be used to build large, complex graphs (there are other modules much more suited to that job). The focus here is on the kinds of data well-suited to the sparklines concept.

Although the basics are there, this module is not yet feature complete.

INTERFACE

CVG::Sparkline->new( $type, $args_hr )

Create a new SVG::Sparkline object of the specified type, using the parameters in the $args_hr hash reference. There are two groups of parameters. Parameters that start with a - character control the SVG::Sparkline object. Parameters that do not start with - are used in attributes in the sparkline itself.

Configuration Parameters

Configuration parameters are independent of the type of sparkline being generated.

-nodecl

The value of this parameter is a boolean that specifies whether the XML declaration statement is to be removed from the generated SVG.

If you are embedding the SVG content directly in another document (maybe HTML), you should pass this parameter with a 1. If you are generating a standalone sparkline document, you should pass a 0.

The -nodecl parameter defaults to 0.

-allns

The value of this parameter is a boolean that specifies whether to supply all potential namespace attributes relating to SVG.

If the value of the parameter is 0 or the parameter is not supplied, only the default SVG namespace is included in the sparkline.

If the value of the parameter is 1, a namespace is supplied for the prefix svg and the prefix xlink.

Attribute Parameters

The attribute parameters passed in $args_hr depend somewhat on the $type. However, some are common.

height

This optional parameter specifies the height of the Sparkline in pixels. The data for the sparkline is scaled to fit this height. If not specified, the default height is 10 pixels.

width

This parameter specifies the width of the Sparkline in pixels. All data is scaled to fit this width. Whether the width parameter is optional or required depends on the sparkline type. The type also determines the default width if one is not specifies.

x

This parameter must be a reference to an array of numbers specifying the x-coordinates of the data set to display. It is required for Line and Area sparklines and ignored for Bar and Whisker sparklines. For the types that require the x parameter, the number of items specified for x and y must be the same.

y

This parameter is required for Line and Whisker sparklines and specifies the y-coordinates of the data set to display. The value of this parameter is an array of numbers.

color

This optional parameter specifies the color for the displayed data as an SVG supported color string. Each sparkline type uses this color slightly differently.

The supported graph types are: Area, Bar, Line, and Whisker. Each type is described below with any parameters specific to that type.

Area

An Area sparkline is a basic line graph with shaded between the line and the x axis. The supplied color attribute determines the shading.

x

The x parameter is required for the Area sparkline type. The value must be a reference to an array of numeric values in increasing order. There must be the same number of x values as y values.

y

The y parameter is required for the Area sparkline type. The value must be a reference to an array of numeric values, where each y value matches the corresponding x value.

width

This parameter is required for the Area sparkline type. The value is the width of the sparkline in pixels.

color

This optional parameter specifies the color of the filled area between the data line and the x-axis as a SVG supported color string. The default value for this parameter is #000 (black).

Bar

The Bar sparkline type is a simple bar graph. This sparkline type does not require any x values.

values

The values parameter is required for the Bar sparkline type. The value must be a reference to an array of numeric values, specifying the height of the corresponding bar.

thick

This optional parameter specifies the thickness of the individual bars on the bar graph. This parameter is ignored if the width parameter is specified. If neither width or thick are specified, the default value of thick is 3.

width

This optional parameter specifies the width of the sparkline in pixels. If the width is not specified, the width of the sparkline is the value of thick times the number of values.

color

This optional parameter specifies the color of the filled area between the data line and the x-axis as a SVG supported color string. The default value for this parameter is #000 (black).

Line

The Line sparkline type is a simple line graph. Both x and y values are required for Line sparklines.

x

The x parameter is required for the Line sparkline type. The value must be a reference to an array of numeric values in increasing order. There must be the same number of x values as y values.

y

The y parameter is required for the Line sparkline type. The value must be a reference to an array of numeric values, where each y value matches the corresponding x value.

width

This parameter is required for the Line sparkline type. The value is the width of the sparkline in pixels.

thick

This optional parameter specifies the thickness of the data line in pixels. If not specified, the default value is 1 pixel.

color

This optional parameter specifies the color of the data line as a SVG supported color string. The default value for this parameter is #000 (black).

Whisker

The Whisker sparkline type shows a sequence of events that can have one of two outcomes (e.g. win/loss). A short line upwards is one of the outcomes and a short line downward is the other outcome. There is also a third possible where no tick is displayed.

values

The values parameter is required for the Whisker sparkline type. The value can be one of three things:

string of '+', '-', or '0'

Where '+' means an uptick, '-' is a down tick, and 0 is no tick.

string of '1' or '0'.

Where '1' means an uptick, and '0' means a downtick.

reference to an array of numbers

Where any positive number is an uptick, any negative number is a downtick, and zero is no tick.

width

This optional parameter specifies the width of the sparkline in pixels. If the width is not specified, the width of the sparkline is the value of thick times 3 times the number of values.

thick

This optional parameter specifies the thickness of the individual whiskers on the whisker chart. The gaps between the whiskers is twice the value of thick. This parameter is ignored if the width parameter is specified. If neither width or thick are specified, the default value of thick is 1.

color

This optional parameter specifies the color of the individual whiskers as a SVG supported color string. The default value for this parameter is #000 (black).

to_string

Convert the SVG::Sparkline object to an XML string.

DIAGNOSTICS

Diagnostic message for the various types are documented in the appropriate SVG::Sparkline::* module.

CONFIGURATION AND ENVIRONMENT

SVG::Sparkline requires no configuration files or environment variables.

DEPENDENCIES

Carp, SVG.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-svg-sparkline@rt.cpan.org, or through the web interface at http://rt.cpan.org.

FUTURE DIRECTIONS

I plan to support more optional features and more intelligence so that the module can do a better job without you specifying everything.

AUTHOR

G. Wade Johnson <wade@anomaly.org>

LICENCE AND COPYRIGHT

Copyright (c) 2009, G. Wade Johnson <wade@anomaly.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.