local-lib5/man/man3/Catalyst::Action::Serialize.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Catalyst::Action::Serialize 3"
 127 .TH Catalyst::Action::Serialize 3 "2010-05-13" "perl v5.8.8" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Catalyst::Action::Serialize \- Serialize Data in a Response
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&    package Foo::Controller::Bar;
 138 \&
 139 \&    _\|_PACKAGE_\|_\->config(
 140 \&        \*(Aqdefault\*(Aq   => \*(Aqtext/x\-yaml\*(Aq,
 141 \&        \*(Aqstash_key\*(Aq => \*(Aqrest\*(Aq,
 142 \&        \*(Aqmap\*(Aq       => {
 143 \&            \*(Aqtext/html\*(Aq          => [ \*(AqView\*(Aq, \*(AqTT\*(Aq, ],
 144 \&            \*(Aqtext/x\-yaml\*(Aq        => \*(AqYAML\*(Aq,
 145 \&            \*(Aqtext/x\-data\-dumper\*(Aq => [ \*(AqData::Serializer\*(Aq, \*(AqData::Dumper\*(Aq ],
 146 \&        }
 147 \&    );
 148 \&
 149 \&    sub end :ActionClass(\*(AqSerialize\*(Aq) {}
 150 .Ve
 151 .SH "DESCRIPTION"
 152 .IX Header "DESCRIPTION"
 153 This action will serialize the body of an \s-1HTTP\s0 Response.  The serializer is
 154 selected by introspecting the \s-1HTTP\s0 Requests content-type header.
 155 .PP
 156 It requires that your Catalyst controller is properly configured to set up the
 157 mapping between Content Type's and Serialization classes.
 158 .PP
 159 The specifics of serializing each content-type is implemented as a plugin to
 160 Catalyst::Action::Serialize.
 161 .PP
 162 Typically, you would use this ActionClass on your \f(CW\*(C`end\*(C'\fR method.  However,
 163 nothing is stopping you from choosing specific methods to Serialize:
 164 .PP
 165 .Vb 3
 166 \&  sub foo :Local :ActionClass(\*(AqSerialize\*(Aq) {
 167 \&     .. populate stash with data ..
 168 \&  }
 169 .Ve
 170 .PP
 171 When you use this module, the request class will be changed to
 172 Catalyst::Request::REST.
 173 .SH "CONFIGURATION"
 174 .IX Header "CONFIGURATION"
 175 .SS "map"
 176 .IX Subsection "map"
 177 Takes a hashref, mapping Content-Types to a given serializer plugin.
 178 .SS "default"
 179 .IX Subsection "default"
 180 This is the 'fall\-back' Content-Type if none of the requested or acceptable
 181 types is found in the \*(L"map\*(R". It must be an entry in the \*(L"map\*(R".
 182 .SS "stash_key"
 183 .IX Subsection "stash_key"
 184 Specifies the key of the stash entry holding the data that is to be serialized.
 185 So if the value is \*(L"rest\*(R", we will serialize the data under:
 186 .PP
 187 .Vb 1
 188 \&  $c\->stash\->{\*(Aqrest\*(Aq}
 189 .Ve
 190 .SS "content_type_stash_key"
 191 .IX Subsection "content_type_stash_key"
 192 Specifies the key of the stash entry that optionally holds an overriding
 193 Content-Type. If set, and if the specified stash entry has a valid value,
 194 then it takes priority over the requested content types.
 195 .PP
 196 This can be useful if you want to dynamically force a particular content type,
 197 perhaps for debugging.
 198 .SH "HELPFUL PEOPLE"
 199 .IX Header "HELPFUL PEOPLE"
 200 Daisuke Maki pointed out that early versions of this Action did not play
 201 well with others, or generally behave in a way that was very consistent
 202 with the rest of Catalyst.
 203 .SH "SEE ALSO"
 204 .IX Header "SEE ALSO"
 205 You likely want to look at Catalyst::Controller::REST, which implements
 206 a sensible set of defaults for doing a \s-1REST\s0 controller.
 207 .PP
 208 Catalyst::Action::Deserialize, Catalyst::Action::REST
 209 .SH "AUTHORS"
 210 .IX Header "AUTHORS"
 211 See Catalyst::Action::REST for authors.
 212 .SH "LICENSE"
 213 .IX Header "LICENSE"
 214 You may distribute this code under the same terms as Perl itself.