| 1 |
NAME |
| 2 |
CGI::Application::Plugin::JSON - easy manipulation of JSON headers |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use CGI::Application::Plugin::JSON ':all'; |
| 6 |
|
| 7 |
# add_json_header() is cumulative |
| 8 |
$self->add_json_header( foo => 'Lorem ipsum...'); |
| 9 |
$self->add_json_header( bar => [ 0, 2, 3, 4 ] ); |
| 10 |
$self->add_json_header( baz => { stuff => 1, more_stuff => 2 } ); |
| 11 |
|
| 12 |
# json_header() is not cumulative |
| 13 |
$self->json_header( foo => 'Lorem ipsum...'); |
| 14 |
|
| 15 |
# in case we're printing our own headers |
| 16 |
print "X-JSON: " . $self->json_header_string(); |
| 17 |
|
| 18 |
# clear out everything in the outgoing JSON headers |
| 19 |
$self->clear_json_header(); |
| 20 |
|
| 21 |
# or send the JSON in the document body |
| 22 |
$self->json_body( { foo => 'Lorem ipsum', bar => [ 0, 2, 3 ] } ); |
| 23 |
|
| 24 |
# send the JSON back in the document body, but execute it using a Javascript callback |
| 25 |
$self->json_callback('alert', { foo => 'Lorem ipsum', bar => [ 0, 2, 3 ] } ); |
| 26 |
|
| 27 |
DESCRIPTION |
| 28 |
When communicating with client-side JavaScript, it is common to send |
| 29 |
data in "X-JSON" HTTP headers or through the document body as |
| 30 |
content-type "application/json". |
| 31 |
|
| 32 |
This plugin adds a couple of convenience methods to make that just a |
| 33 |
little bit easier. |
| 34 |
|
| 35 |
HEADER METHODS |
| 36 |
json_header |
| 37 |
This method takes name-value pairs and sets them to be used in the |
| 38 |
outgoing JSON. It is not cummulative and works similarly to |
| 39 |
"header_props". Use it only if you have all of the values up front. In |
| 40 |
most cases add_json_header is probably what you want. |
| 41 |
|
| 42 |
# only the 2nd call will actually set data that will be sent |
| 43 |
$self->json_header( foo => 'Lorem ipsum...'); |
| 44 |
$self->json_header( bar => [ 0, 2, 3, 4 ] ); |
| 45 |
|
| 46 |
add_json_header |
| 47 |
This method takes name-value pairs and sets them to be used in the |
| 48 |
outgoing JSON. It is cummulative and works similarly to "header_add"; |
| 49 |
meaning multiple calls will add to the hash of outgoing values. |
| 50 |
|
| 51 |
# both 'foo' and 'bar' will exist in the hash sent out |
| 52 |
$self->json_header( foo => 'Lorem ipsum...'); |
| 53 |
$self->json_header( bar => [ 0, 2, 3, 4 ] ); |
| 54 |
|
| 55 |
clear_json_header |
| 56 |
This method will remove anything that was previously set by both |
| 57 |
json_header and add_json_header. This means that no "X-JSON" header will |
| 58 |
be sent. |
| 59 |
|
| 60 |
json_header_string |
| 61 |
This method will create the actual HTTP header string that will be sent |
| 62 |
to the browser. This plugin uses it internally to send the header, but |
| 63 |
it might be useful to use directly if you are printing your own HTTP |
| 64 |
headers (using a "header_type" of "none"). |
| 65 |
|
| 66 |
$self->header_type('none'); |
| 67 |
print $self->json_header_string(); |
| 68 |
|
| 69 |
json_header_value |
| 70 |
This method will return the values being sent in the JSON header. If you |
| 71 |
pass in the key of the value you want, you will get just that value. |
| 72 |
Else all name-value pairs will be returned. |
| 73 |
|
| 74 |
my $value = $self->json_header_value('foo'); |
| 75 |
|
| 76 |
my %values = $self->json_header_value(); |
| 77 |
|
| 78 |
BODY METHODS |
| 79 |
json_body |
| 80 |
This method will take the given Perl structure, turn it into JSON, set |
| 81 |
the appropriate content-type, and then return the JSON. |
| 82 |
|
| 83 |
return $self->json_body({ foo => 'stuff', bar => [0,1,2,3]} ); |
| 84 |
|
| 85 |
json_callback |
| 86 |
This method will take the given Perl structure, turn it into JSON, set |
| 87 |
the appropriate content-type, and then return a Javascript snippet where |
| 88 |
the given callback is called with the resulting JSON. |
| 89 |
|
| 90 |
return $self->json_callback('alert', { foo => 'stuff', bar => [0,1,2,3]} ); |
| 91 |
|
| 92 |
# would result in something like the following being sent to the client |
| 93 |
alert({ foo => 'stuff', bar => [0,1,2,3]}); |
| 94 |
|
| 95 |
to_json |
| 96 |
This method is just a convenient wrapper around JSON::Any's "encode". |
| 97 |
|
| 98 |
from_json |
| 99 |
This method is just a convenient wrapper around JSON::Any's "decode". |
| 100 |
|
| 101 |
AUTHOR |
| 102 |
Michael Peters, "<[email protected]>" |
| 103 |
|
| 104 |
BUGS |
| 105 |
Please report any bugs or feature requests to |
| 106 |
"[email protected]", or through the web |
| 107 |
interface at |
| 108 |
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Application-Plugin-J |
| 109 |
SON>. I will be notified, and then you'll automatically be notified of |
| 110 |
progress on your bug as I make changes. |
| 111 |
|
| 112 |
COPYRIGHT & LICENSE |
| 113 |
Copyright 2006 Michael Peters, All Rights Reserved. |
| 114 |
|
| 115 |
This program is free software; you can redistribute it and/or modify it |
| 116 |
under the same terms as Perl itself. |
| 117 |
|