Skip to content
Browse files

Release 1.01; regenerate README

  • Loading branch information...
1 parent a36c0dc commit 8dd16c711b81f22fe7a2da311c232abfde087a87 @gisle committed Jun 11, 2009
Showing with 140 additions and 68 deletions.
  1. +6 −5 Changes
  2. +132 −61 README
  3. +2 −2 lib/URI/GoogleChart.pm
View
11 Changes
@@ -1,4 +1,10 @@
_______________________________________________________________________________
+2009-06-11 Release 1.01
+
+Doc tweak; regenerate the README file
+
+
+_______________________________________________________________________________
2009-06-11 Release 1.00
Gisle Aas (10):
@@ -14,7 +20,6 @@ Gisle Aas (10):
Fix typos in the synopis example; show ranges
-
_______________________________________________________________________________
2009-04-05 Release 0.04
@@ -24,7 +29,6 @@ perl hash key ordering.
Move the 'chd' parameter last so it gets out of the way
-
_______________________________________________________________________________
2009-03-30 Release 0.03
@@ -38,20 +42,17 @@ More color aliases.
Improved documentation.
-
_______________________________________________________________________________
2009-03-27 Release 0.02
Include examples.html in the distribution and fixup the documentation of
the margin option.
-
_______________________________________________________________________________
2009-03-26 Release 0.01
Initial CPAN release
-
_______________________________________________________________________________
View
193 README
@@ -2,32 +2,49 @@ NAME
URI::GoogleChart - Generate Google Chart URIs
SYNOPSIS
- use URI::GoggleChart;
- my $chart = URI::GoogleChart->new("line", 300, 100,
- data => [45, 80, 100, 33],
+ use URI::GoogleChart;
+ my $chart = URI::GoogleChart->new("lines", 300, 100,
+ data => [45, 80, 55, 68],
+ range_show => "left",
+ range_round => 1,
);
+ # save chart to a file
+ use LWP::Simple qw(getstore);
+ getstore($chart, "chart.png");
+
+ # or embed chart in an HTML file
+ use HTML::Entities;
+ my $enc_chart = encode_entities($chart);
+
+ open(my $fh, ">", "chart.html") || die;
+ print $fh qq(
+ <h1>My Chart</h1>
+ <p><img src="$enc_chart"></p>
+ );
+ close($fh) || die;
+
DESCRIPTION
- This module provide a constructor method for Google Chart URIs. Google
- will serve back PNG images of charts controlled by the provided
- parameters when these URI are dereferenced. Normally these URIs will be
- embedded as "<img src='$chart'>" tags in HTML documents.
+ This module provide a constructor method for Google Chart URLs. When
+ dereferenced Google will serve back PNG images of charts based on the
+ provided parameters.
The Google Chart service is described at
- <http://code.google.com/apis/chart/> and these pages also define the API
- in terms of the parameters these URIs take. This module make it easier
- to generate URIs that conform to this API as it automatically takes care
- of data encoding and scaling, as well as hiding most of the cryptic
- parameter names that the API uses in order to generate shorter URIs.
+ <http://code.google.com/apis/chart/> and these pages also define the Web
+ API in terms of the parameters these URLs take. This module make it
+ easier to generate URLs that conform to this API as it automatically
+ takes care of data encoding and scaling, as well as hiding most of the
+ cryptic parameter names that the API uses in order to generate shorter
+ URLs.
The following constructor method is provided:
$uri = URI::GoogleChart->new( $type, $width, $height, %opt )
- The constructor method's 3 first arguments are mandatory and they
+ The constructor method's first 3 arguments are mandatory and they
define the type of chart to generate and the dimension of the image
- in pixels. The rest of the arguments are provided as key/value
- pairs. The return value is an HTTP URI object, which can also be
- treated as a string.
+ in pixels. Additional arguments are provided as key/value pairs. The
+ return value is an HTTP URI object, which can also be treated as a
+ string.
The $type argument can either be one of the type code documented at
the Google Charts page or one of the following more readable
@@ -60,54 +77,81 @@ DESCRIPTION
south_america
usa
- The key/value pairs can either be one of the "chXXX" codes
- documented on the Google Chart pages or one of the following:
+ The additional arguments in the form of key/value pairs can either
+ be one of the "chXXX" parameters documented on the Google Chart
+ pages or one of the following:
data => [{ v => [$v1, $v2,...], %opt }, ...]
data => [[$v1, $v2,...], [$v1, $v2,...], ...]
data => [$v1, $v2,...]
data => $v1
The data to be charted is provided as an array of data series.
- Each series is defined by a hash with the "v" element being an
- array of data points in the series. Missing data points should
- be provided as "undef". Other hash elements can be provided to
- define various properties of the series. These are described
- below.
+ In the most general form each series is defined by a hash with
+ the "v" element being an array of data points (numbers) in the
+ series. Missing data points should be provided as "undef". Other
+ hash elements can be provided to define various properties of
+ the series. These are described below.
As a short hand when you don't need to define other properties
- besides the data points you can just provide an array of numbers
+ besides the data points you can provide an array of numbers
instead of the series hash.
As a short hand when you only have a single data series, you can
- just provide a single array of numbers, and finally if you only
- have a single number you can provide it without wrapping it in
- an array.
+ provide a single array of numbers, and finally if you only have
+ a single number you can provide it without wrapping it in an
+ array.
- The following data series properties can be provided.
+ Data series belong to ranges. A range is defined by a minimum
+ and a maximum value. Data points are scaled so that they are
+ plotted relative to the range they belong to. For example if the
+ range is (5 .. 10) then a data point value of 7.5 is plotted in
+ the middle of the chart area. Ranges are automatically
+ calculated based on the data provided, but you can also force
+ certain minimum and maximum values to apply.
+
+ The following data series properties can be provided in addition
+ to "v" described above:
- The "group" property can be used to group data series together.
- Series that have the same group value belong to the same group.
- Values in the same group are scaled based on the minimum and
- maximum data point provided in that group. Data series without a
- "group" property belong to the default group.
+ The "range" property can be used to group data series together
+ that belong to the same range. The value of the "range" property
+ is a range name. Data series without a "range" property belong
+ to the default range.
min => $num
max => $num
- Defines the minimum and maximum value for the default group. If
- not provided the minimum and maximum is calculated from the data
- points belonging to this group. Chart types that plot relative
- values make the default minimum 0 so the relative size of the
- data points stay the same after scaling.
-
- The data points are scaled so that they are plotted relative to
- the ($min .. $max) range. For example if the ($min .. $max)
- range is (5 .. 10) then a data point value of 7.5 is plotted in
- the middle of the chart area.
-
- group => { $name => { min => $min, max => $max }, ...},
- Define parameters for named data series groups. Currently you
- can only set up the minimum and maximum values used for scaling
- the data points.
+ Defines the default minimum and maximum value for the default
+ range. If not provided the minimum and maximum is calculated
+ from the data points belonging to this range.
+
+ The specified minimum or maximum are ignored if some of data
+ values provided are outside this range.
+
+ Chart types that plot relative values (like bar charts or venn
+ diagrams) should use 0 as the minimum, as this make the relative
+ size of the data points stay the same after scaling. Because of
+ this the default default minimum for these charts is 0, so you
+ don't actually need to specify it.
+
+ range_round => $bool
+ Extend the default range so that the min/max values are nice
+ multiples of 1, 5, 10, 50, 100,... and such numbers. This gives
+ the chart more "air" and look better if you display the range of
+ values with "range_show".
+
+ range_show => "left"
+ range_show => "right"
+ range_show => "top"
+ range_show => "bottom"
+ Makes the given axis show the range of values charted for the
+ default range.
+
+ range => { $name => \%opt, ...},
+ Define parameters for named data series ranges. The range named
+ "" is the default range.
+
+ The option values that can be set are "min", "max", "round",
+ "show". See the description of the corresponding entry for the
+ default range above.
encoding => "t"
encoding => "s"
@@ -118,20 +162,20 @@ DESCRIPTION
Verbosity matters as some web client might refuse to dereference
URLs that are too long.
- The "t" encoding is the most readable and verbose. It might
- consume up to 5 bytes per data point. It provide a resolution of
- 1/1000.
+ The "t" (or "text") encoding is the most readable and verbose.
+ It might consume up to 5 bytes per data point. It provide a
+ resolution of 1/1000.
- The "s" encoding is the most compact; only consuming 1 byte per
- data point. It provide a resolution of 1/62.
+ The "s" (or "simple") encoding is the most compact; only
+ consuming 1 byte per data point. It provide a resolution of
+ 1/62.
- The "e" encoding provides the most resolution and it consumes 2
- bytes per data point. It provide a resolution of 1/4096.
+ The "e" (or "extended") encoding provides the most resolution
+ and it consumes 2 bytes per data point. It provide a resolution
+ of 1/4096.
- The default encoding is currently "t"; but expect this to
- change. The default ought to be automatically selected based on
- the resolution of the chart and the number of data points
- provided.
+ The default encoding is automatically selected based on the
+ resolution of the chart and the number of data points provided.
color => $color
color => [$color1, $color2, ...]
@@ -140,19 +184,46 @@ DESCRIPTION
"RRGGBBAA" form. When you use this interface you might also use
"RGB" form as well as some comon names like "red", "blue",
"green", "white", "black",... which are expanded to the
- canonical form in the URI.
+ canonical form in the URL.
+
+ The built in colors are the 16 colors of the HTML specification
+ (see <http://en.wikipedia.org/wiki/HTML_color_names>). If you
+ want to use additional color names you can assign your mapping
+ to the %URI::GoogleChart::COLOR_ALIAS hash before start creating
+ charts. Example:
+
+ local $URI::GoogleChart::COLOR_ALIAS{"gold"} = "FFD700";
+
+ background => $color
+ Sets the color for the chart background. See description for
+ color above for how to specify color values. The color value
+ "transparent" gives you a fully transparent background.
title => $str
- title => { text => $str, color => $color, fontsize => $fontsize }
+ title => [ $str, $color, $fontsize ]
Sets the title for the chart; optionally changing the color and
fontsize used for the title.
+ label = $str
+ label = [ $str, $str,... ]
+ Labels the data (or data series) of the chart.
+
+ rotate => $degrees
+ Rotate the orientation of a pie chart (clockwise).
+
+ The first slice starts at the right side of the pie (at 3
+ o'clock). If you rotate the pie 90 degrees the first slice
+ starts at the bottom. If you rotate -90 degrees (or 270) the
+ first slices starts at the top of the pie.
+
margin => $num
margin => [ $left, $right, $top, $bottom ]
Sets the chart margins in pixels. If a single number is provided
then all the margins are set to this number of pixels.
SEE ALSO
+ <http://cpansearch.perl.org/src/GAAS/URI-GoogleChart-1.01/examples.html>
+
<http://code.google.com/apis/chart/>
URI
View
4 lib/URI/GoogleChart.pm
@@ -2,7 +2,7 @@ package URI::GoogleChart;
use strict;
-our $VERSION = "1.00";
+our $VERSION = "1.01";
use URI;
use Carp qw(croak carp);
@@ -661,7 +661,7 @@ the margins are set to this number of pixels.
=head1 SEE ALSO
-L<http://cpansearch.perl.org/src/GAAS/URI-GoogleChart-1.00/examples.html>
+L<http://cpansearch.perl.org/src/GAAS/URI-GoogleChart-1.01/examples.html>
L<http://code.google.com/apis/chart/>

0 comments on commit 8dd16c7

Please sign in to comment.
Something went wrong with that request. Please try again.