local-lib5/man/man3/Catalyst::TraitFor::Request::REST::ForBrowsers.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::TraitFor::Request::REST::ForBrowsers 3"
 127 .TH Catalyst::TraitFor::Request::REST::ForBrowsers 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::TraitFor::Request::REST::ForBrowsers \- A request trait for REST and browsers
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&    package MyApp;
 138 \&    use Moose;
 139 \&    use namespace::autoclean;
 140 \&
 141 \&    use Catalyst;
 142 \&    use CatalystX::RoleApplicator;
 143 \&
 144 \&    extends \*(AqCatalyst\*(Aq;
 145 \&
 146 \&    _\|_PACKAGE_\|_\->apply_request_class_roles(qw[
 147 \&        Catalyst::TraitFor::Request::REST::ForBrowsers
 148 \&    ]);
 149 .Ve
 150 .SH "DESCRIPTION"
 151 .IX Header "DESCRIPTION"
 152 Writing REST-y apps is a good thing, but if you're also trying to support web
 153 browsers, you're probably going to need some hackish workarounds. This module
 154 provides those workarounds for you.
 155 .PP
 156 Specifically, it lets you do two things. First, it lets you \*(L"tunnel\*(R" \s-1PUT\s0 and
 157 \&\s-1DELETE\s0 requests across a \s-1POST\s0, since most browsers do not support \s-1PUT\s0 or
 158 \&\s-1DELETE\s0 actions (as of early 2009, at least).
 159 .PP
 160 Second, it provides a heuristic to check if the client is a web browser,
 161 regardless of what content types it claims to accept. The reason for this is
 162 that while a browser might claim to accept the \*(L"application/xml\*(R" content type,
 163 it's really not going to do anything useful with it, and you're best off
 164 giving it \s-1HTML\s0.
 165 .SH "METHODS"
 166 .IX Header "METHODS"
 167 This class provides the following methods:
 168 .ie n .SS "$request\->method"
 169 .el .SS "\f(CW$request\fP\->method"
 170 .IX Subsection "$request->method"
 171 This method works just like \f(CW\*(C`Catalyst::Request\->method()\*(C'\fR except it
 172 allows for tunneling of \s-1PUT\s0 and \s-1DELETE\s0 requests via a \s-1POST\s0.
 173 .PP
 174 Specifically, you can provide a form element named \*(L"x\-tunneled-method\*(R" which
 175 can override the request method for a \s-1POST\s0. This \fIonly\fR works for a \s-1POST\s0, not
 176 a \s-1GET\s0.
 177 .PP
 178 You can also use a header named \*(L"x\-http-method-override\*(R" instead (Google uses
 179 this header for its APIs).
 180 .ie n .SS "$request\->looks_like_browser"
 181 .el .SS "\f(CW$request\fP\->looks_like_browser"
 182 .IX Subsection "$request->looks_like_browser"
 183 This attribute provides a heuristic to determine whether or not the request
 184 \&\fIappears\fR to come from a browser. You can use this however you want. I
 185 usually use it to determine whether or not to give the client a full \s-1HTML\s0 page
 186 or some sort of serialized data.
 187 .PP
 188 This is a heuristic, and like any heuristic, it is probably wrong
 189 sometimes. Here is how it works:
 190 .IP "\(bu" 4
 191 If the request includes a header \*(L"X\-Request-With\*(R" set to either \*(L"\s-1HTTP\s0.Request\*(R"
 192 or \*(L"XMLHttpRequest\*(R", this returns false. The assumption is that if you're
 193 doing \s-1XHR\s0, you don't want the request treated as if it comes from a browser.
 194 .IP "\(bu" 4
 195 If the client makes a \s-1GET\s0 request with a query string parameter
 196 \&\*(L"content-type\*(R", and that type is \fInot\fR an \s-1HTML\s0 type, it is \fInot\fR a browser.
 197 .IP "\(bu" 4
 198 If the client provides an Accept header which includes \*(L"*/*\*(R" as an accepted
 199 content type, the client is a browser. Specifically, it is \s-1IE7\s0, which submits
 200 an Accept header of \*(L"*/*\*(R". \s-1IE7\s0's Accept header does not include any html types
 201 like \*(L"text/html\*(R".
 202 .IP "\(bu" 4
 203 If the client provides an Accept header and accepts either \*(L"text/html\*(R" or
 204 \&\*(L"application/xhtml+xml\*(R" it is a browser.
 205 .IP "\(bu" 4
 206 If it provides an Accept header of any sort, it is \fInot\fR a browser.
 207 .IP "\(bu" 4
 208 The default is that the client is a browser.
 209 .PP
 210 This all works well for my apps, but read it carefully to make sure it meets
 211 your expectations before using it.
 212 .SH "AUTHOR"
 213 .IX Header "AUTHOR"
 214 Dave Rolsky, \f(CW\*(C`<autarch@urth.org>\*(C'\fR
 215 .SH "BUGS"
 216 .IX Header "BUGS"
 217 Please report any bugs or feature requests to
 218 \&\f(CW\*(C`bug\-catalyst\-action\-rest@rt.cpan.org\*(C'\fR, or through the web interface at
 219 <http://rt.cpan.org>. We will be notified, and then you'll automatically be
 220 notified of progress on your bug as I make changes.
 221 .SH "COPYRIGHT & LICENSE"
 222 .IX Header "COPYRIGHT & LICENSE"
 223 Copyright 2008\-2010 Dave Rolsky, All Rights Reserved.
 224 .PP
 225 This program is free software; you can redistribute it and/or modify it under
 226 the same terms as Perl itself.