Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Perl - JSON plugin for CGI::Application
Perl
Branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib/CGI/Application/Plugin
t
.gitignore
Build.PL
Changes
MANIFEST
MANIFEST.SKIP
META.yml
Makefile.PL
README
TODO

README

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();
    
        # check to see if there's a JSON header or body in play
        return if $self->has_json();

        # 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 "text/x-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.

  has_json
    This method will check to see if there's a JSON header (or body) in play
    and return true. This is useful in the case of wanting to skip shell
    templates in a generic cgiapp_postrun method:

        sub cgiapp_postrun {
            my ( $self, $output_ref ) = @_;
            return if $self->has_json();
            # proceed w/ shell...
        }

  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]});

  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-J
    SON>. 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.

Something went wrong with that request. Please try again.