Debian Codegraph @

README

raw
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