.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CGI::Application::Plugin::JSON 3pm"
.TH CGI::Application::Plugin::JSON 3pm "2022-06-09" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Application::Plugin::JSON \- easy manipulation of JSON headers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use CGI::Application::Plugin::JSON \*(Aq:all\*(Aq;
\&
\&    # add_json_header() is cumulative
\&    $self\->add_json_header( foo => \*(AqLorem ipsum...\*(Aq);
\&    $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 => \*(AqLorem ipsum...\*(Aq);
\&
\&    # in case we\*(Aqre 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 => \*(AqLorem ipsum\*(Aq, bar => [ 0, 2, 3 ] } );
\&
\&    # send the JSON back in the document body, but execute it using a Javascript callback
\&    $self\->json_callback(\*(Aqalert\*(Aq, { foo => \*(AqLorem ipsum\*(Aq, bar => [ 0, 2, 3 ] } );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
When communicating with client-side JavaScript, it is common to send
data in \f(CW\*(C`X\-JSON\*(C'\fR \s-1HTTP\s0 headers or through the document body as content-type
\&\f(CW\*(C`application/json\*(C'\fR.
.PP
This plugin adds a couple of convenience methods to make that just a 
little bit easier.
.SH "HEADER METHODS"
.IX Header "HEADER METHODS"
.SS "json_header"
.IX Subsection "json_header"
This method takes name-value pairs and sets them to be used in the outgoing
\&\s-1JSON.\s0 It is not cummulative and works similarly to \f(CW\*(C`header_props\*(C'\fR. Use it
only if you have all of the values up front. In most cases add_json_header
is probably what you want.
.PP
.Vb 3
\&    # only the 2nd call will actually set data that will be sent
\&    $self\->json_header( foo => \*(AqLorem ipsum...\*(Aq);
\&    $self\->json_header( bar => [ 0, 2, 3, 4 ] );
.Ve
.SS "add_json_header"
.IX Subsection "add_json_header"
This method takes name-value pairs and sets them to be used in the outgoing
\&\s-1JSON.\s0 It is cummulative and works similarly to \f(CW\*(C`header_add\*(C'\fR; meaning multiple
calls will add to the hash of outgoing values.
.PP
.Vb 3
\&    # both \*(Aqfoo\*(Aq and \*(Aqbar\*(Aq will exist in the hash sent out 
\&    $self\->json_header( foo => \*(AqLorem ipsum...\*(Aq);
\&    $self\->json_header( bar => [ 0, 2, 3, 4 ] );
.Ve
.SS "clear_json_header"
.IX Subsection "clear_json_header"
This method will remove anything that was previously set by both json_header
and add_json_header. This means that no \f(CW\*(C`X\-JSON\*(C'\fR header will be sent.
.SS "json_header_string"
.IX Subsection "json_header_string"
This method will create the actual \s-1HTTP\s0 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 \s-1HTTP\s0 headers
(using a \f(CW\*(C`header_type\*(C'\fR of \f(CW\*(C`none\*(C'\fR).
.PP
.Vb 2
\&    $self\->header_type(\*(Aqnone\*(Aq);
\&    print $self\->json_header_string();
.Ve
.SS "json_header_value"
.IX Subsection "json_header_value"
This method will return the values being sent in the \s-1JSON\s0 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.
.PP
.Vb 1
\&    my $value = $self\->json_header_value(\*(Aqfoo\*(Aq);
\&
\&    my %values = $self\->json_header_value();
.Ve
.SH "BODY METHODS"
.IX Header "BODY METHODS"
.SS "json_body"
.IX Subsection "json_body"
This method will take the given Perl structure, turn it
into \s-1JSON,\s0 set the appropriate content-type, and then
return the \s-1JSON.\s0
.PP
.Vb 1
\&    return $self\->json_body({ foo => \*(Aqstuff\*(Aq, bar => [0,1,2,3]} );
.Ve
.SS "json_callback"
.IX Subsection "json_callback"
This method will take the given Perl structure, turn it
into \s-1JSON,\s0 set the appropriate content-type, and then
return a Javascript snippet where the given callback
is called with the resulting \s-1JSON.\s0
.PP
.Vb 1
\&    return $self\->json_callback(\*(Aqalert\*(Aq, { foo => \*(Aqstuff\*(Aq, bar => [0,1,2,3]} );
\&
\&    # would result in something like the following being sent to the client
\&    alert({ foo => \*(Aqstuff\*(Aq, bar => [0,1,2,3]});
.Ve
.SH "MISC METHODS"
.IX Header "MISC METHODS"
.SS "to_json"
.IX Subsection "to_json"
This method is just a convenient wrapper around JSON::Any's \f(CW\*(C`encode\*(C'\fR.
.SS "from_json"
.IX Subsection "from_json"
This method is just a convenient wrapper around JSON::Any's \f(CW\*(C`decode\*(C'\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
Michael Peters, \f(CW\*(C`<mpeters@plusthree.com>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-cgi\-application\-plugin\-viewsource@rt.cpan.org\*(C'\fR, 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.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2006 Michael Peters, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.