NAME

       CGI::Application::Plugin::JSON - easy manipulation of JSON headers

SYNOPSIS

           use CGI::Application::Plugin::JSON ':all';

           # add_json_header() is cumulative
           $self->add_json_header( foo => 'Lorem ipsum...');
           $self->add_json_header( bar => [ 0, 2, 3, 4 ] );
           $self->add_json_header( baz => { stuff => 1, more_stuff => 2 } );

           # json_header() is not cumulative
           $self->json_header( foo => 'Lorem ipsum...');

           # in case we're printing our own headers
           print "X-JSON: " . $self->json_header_string();

           # clear out everything in the outgoing JSON headers
           $self->clear_json_header();

           # or send the JSON in the document body
           $self->json_body( { foo => 'Lorem ipsum', bar => [ 0, 2, 3 ] } );

           # send the JSON back in the document body, but execute it using a Javascript callback
           $self->json_callback('alert', { foo => 'Lorem ipsum', bar => [ 0, 2, 3 ] } );

DESCRIPTION

       When communicating with client-side JavaScript, it is common to send data in "X-JSON" HTTP
       headers or through the document body as content-type "application/json".

       This plugin adds a couple of convenience methods to make that just a little bit easier.

HEADER METHODS

   json_header
       This method takes name-value pairs and sets them to be used in the outgoing JSON. It is
       not cummulative and works similarly to "header_props". Use it only if you have all of the
       values up front. In most cases add_json_header is probably what you want.

           # only the 2nd call will actually set data that will be sent
           $self->json_header( foo => 'Lorem ipsum...');
           $self->json_header( bar => [ 0, 2, 3, 4 ] );

   add_json_header
       This method takes name-value pairs and sets them to be used in the outgoing JSON. It is
       cummulative and works similarly to "header_add"; meaning multiple calls will add to the
       hash of outgoing values.

           # both 'foo' and 'bar' will exist in the hash sent out
           $self->json_header( foo => 'Lorem ipsum...');
           $self->json_header( bar => [ 0, 2, 3, 4 ] );

   clear_json_header
       This method will remove anything that was previously set by both json_header and
       add_json_header. This means that no "X-JSON" header will be sent.

   json_header_string
       This method will create the actual HTTP header string that will be sent to the browser.
       This plugin uses it internally to send the header, but it might be useful to use directly
       if you are printing your own HTTP headers (using a "header_type" of "none").

           $self->header_type('none');
           print $self->json_header_string();

   json_header_value
       This method will return the values being sent in the JSON header.  If you pass in the key
       of the value you want, you will get just that value. Else all name-value pairs will be
       returned.

           my $value = $self->json_header_value('foo');

           my %values = $self->json_header_value();

BODY METHODS

   json_body
       This method will take the given Perl structure, turn it into JSON, set the appropriate
       content-type, and then return the JSON.

           return $self->json_body({ foo => 'stuff', bar => [0,1,2,3]} );

   json_callback
       This method will take the given Perl structure, turn it into JSON, set the appropriate
       content-type, and then return a Javascript snippet where the given callback is called with
       the resulting JSON.

           return $self->json_callback('alert', { foo => 'stuff', bar => [0,1,2,3]} );

           # would result in something like the following being sent to the client
           alert({ foo => 'stuff', bar => [0,1,2,3]});

MISC METHODS

   to_json
       This method is just a convenient wrapper around JSON::Any's "encode".

   from_json
       This method is just a convenient wrapper around JSON::Any's "decode".

AUTHOR

       Michael Peters, "<mpeters@plusthree.com>"

BUGS

       Please report any bugs or feature requests to
       "bug-cgi-application-plugin-viewsource@rt.cpan.org", or through the web interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-JSON>.  I will be
       notified, and then you'll automatically be notified of progress on your bug as I make
       changes.

COPYRIGHT & LICENSE

       Copyright 2006 Michael Peters, All Rights Reserved.

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