CGI::A...::JSON(3pm)

💖 CGI::Application::Plugin::JSON — bestie edition 💖

okay so this is the manual page for CGI::Application::Plugin::JSON (3pm), from the User Contributed Perl Documentation, and it's literally about easy manipulation of JSON headers. yes queen, we're doing JSON today. 🎀

---

✨ NAME ✨

CGI::Application::Plugin::JSON — easy manipulation of JSON headers. that's it, that's the whole vibe. 🦋

---

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

look at that. gorgeous. no notes. 💅

---

👑 DESCRIPTION 👑

so when you're talking to client-side JavaScript (your bestie on the other side of the wire, fr), it's super 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. a couple of little helpers, so you don't have to do it all by hand. 🫶

---

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

heads up bestie: it is NOT cumulative. that first call? gone. evaporated. the second call ate it. 💀 if you're calling this more than once you probably wanted add_json_header instead.

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

this one's the collector. it keeps everything. it's giving main character energy, honestly. ✨

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.

the reset button. the fresh start. the clean slate era. 🧹

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();

one key? you get one value. no key? you get the whole squad. 🌈

---

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

perl hash goes in, JSON comes out, content-type gets handled. iconic behavior. 🔥

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

JSONP-core. your callback gets called with the goods. 🌸

---

🎀 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".

two lil shortcuts, one for out, one for in. balanced. symmetrical. slay. 💫

---

🙈 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.

found a bug? tell the author, not the group chat. the RT queue is right there and you get auto-updates on the fix. 💅

---

⭐ 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.

---

okay bestie that's the whole page, no cap, nothing skipped. 🫶 this was CGI::A...::JSON(3pm) — User Contributed Perl Documentation — and the version you're looking at is perl v5.34.0, dated 2022-06-09. now go forth and send some JSON. periodt. 💖✨🎀