NAME

VERSION

DESCRIPTION

OVERVIEW

This module is attempts to hide the gory details of preparing your data before sending it to a JSON serializer - more specifically, hiding some of the hoops that have to be jump through for making sure your data serializes to the right data types.

More about the Google Visualization API <http://code.google.com/apis/visualization/documentation/reference.html#dataparam>.

Every effort has been made to keep naming conventions as close as possible to those in the API itself.

To use this module, a reasonable knowledge of Perl is assumed. You should be familiar with Perl references and Perl objects.

SYNOPSIS

 use Data::Google::Visualization::DataTable;

 my $datatable = Data::Google::Visualization::DataTable->new();

 $datatable->add_columns(
        { id => 'date',     label => "A Date",        type => 'date', p => {}},
        { id => 'datetime', label => "A Datetime",    type => 'datetime' },
        { id => 'timeofday',label => "A Time of Day", type => 'timeofday' },
        { id => 'bool',     label => "True or False", type => 'boolean' },
        { id => 'number',   label => "Number",        type => 'number' },
        { id => 'string',   label => "Some String",   type => 'string' },
 );

 $datatable->add_rows(

 # Add as array-refs
        [
                { v => DateTime->new() },
                { v => Time::Piece->new(), f => "Right now!" },
                { v => [6, 12, 1], f => '06:12:01' },
                { v => 1, f => 'YES' },
                15.6, # If you're getting lazy
                { v => 'foobar', f => 'Foo Bar', p => { display => 'none' } },
        ],

 # And/or as hash-refs (but only if you defined id's for each of your columns)
        {
                date      => DateTime->new(),
                datetime  => { v => Time::Piece->new(), f => "Right now!" },
                timeofday => [6, 12, 1],
                bool      => 1,
                number    => 15.6,
                string    => { v => 'foobar', f => 'Foo Bar' },
        },

 );

 # Get the data...

 # Fancy-pants
 my $output = $datatable->output_javascript(
        columns => ['date','number','string' ],
        pretty  => 1,
 );

 # Vanilla
 my $output = $datatable->output_javascript();

COLUMNS, ROWS AND CELLS

 Perl:
  date => [ 5, 4, 3 ]
 JS:
  new Date( 5, 4, 3 )

METHODS

 $object->pedantic(0);

JSON vs Javascript

 {"v":new Date( 2011, 2, 21, 2, 6, 25 )}

which is valid Javascript, but not valid JSON.

DATES AND TIMES

 new Date( 2011, 2, 21, 2, 6, 25 )

in Javascript, what timezone is that? If you guessed UTC because that would be The Right Thing To Do, sadly you guessed wrong - it's actually set in the timezone of the client. And as you don't know what the client's timezone is, if you're going to actually use this data for anything other than display to that user, you're a little screwed.

Even if we don't attempt to rescue that, if you pass in an Epoch timestamp, I have no idea which timezone you want me to use to convert that in to the above. We started off using "localtime", which shows I hadn't really thought about it, and will continue to use it for backwards compatibility, but:

Don't pass this module epoch time stamps. Either do the conversion in your code using "localtime" or "gmtime", or pass in a DateTime object whose "<-"hour>> and friends return the right thing.

We accept four types of date input, and this is how we handle each one:

 Thu, 01 Jan 1970 00:00:00 GMT-0400

 new Date("Thu, 01 Jan 1970 00:00:00 GMT-0400")

BUG BOUNTY

$20 donated 31Dec2010 to TPF re properties handling bug <https://rt.cpan.org/Ticket/Display.html?id=64356>

$10 donated 11Nov2010 to TPF re null display bug <https://rt.cpan.org/Ticket/Display.html?id=62899>

SUPPORT

AUTHOR

SEE ALSO

JSON::XS - The underlying module

Google Visualization API <http://code.google.com/apis/visualization/documentation/reference.html#dataparam>.

Github Page for this code <https://github.com/sheriff/data-google-visualization-datatable-perl>

COPYRIGHT

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