Add built local::lib

[catagits/Gitalist.git] / local-lib5 / man / man3 / Catalyst::TraitFor::Request::REST::ForBrowsers.3pm

.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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 "Catalyst::TraitFor::Request::REST::ForBrowsers 3"
.TH Catalyst::TraitFor::Request::REST::ForBrowsers 3 "2010-05-13" "perl v5.8.8" "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"
Catalyst::TraitFor::Request::REST::ForBrowsers \- A request trait for REST and browsers
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    package MyApp;
\&    use Moose;
\&    use namespace::autoclean;
\&
\&    use Catalyst;
\&    use CatalystX::RoleApplicator;
\&
\&    extends \*(AqCatalyst\*(Aq;
\&
\&    _\|_PACKAGE_\|_\->apply_request_class_roles(qw[
\&        Catalyst::TraitFor::Request::REST::ForBrowsers
\&    ]);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Writing REST-y apps is a good thing, but if you're also trying to support web
browsers, you're probably going to need some hackish workarounds. This module
provides those workarounds for you.
.PP
Specifically, it lets you do two things. First, it lets you \*(L"tunnel\*(R" \s-1PUT\s0 and
\&\s-1DELETE\s0 requests across a \s-1POST\s0, since most browsers do not support \s-1PUT\s0 or
\&\s-1DELETE\s0 actions (as of early 2009, at least).
.PP
Second, it provides a heuristic to check if the client is a web browser,
regardless of what content types it claims to accept. The reason for this is
that while a browser might claim to accept the \*(L"application/xml\*(R" content type,
it's really not going to do anything useful with it, and you're best off
giving it \s-1HTML\s0.
.SH "METHODS"
.IX Header "METHODS"
This class provides the following methods:
.ie n .SS "$request\->method"
.el .SS "\f(CW$request\fP\->method"
.IX Subsection "$request->method"
This method works just like \f(CW\*(C`Catalyst::Request\->method()\*(C'\fR except it
allows for tunneling of \s-1PUT\s0 and \s-1DELETE\s0 requests via a \s-1POST\s0.
.PP
Specifically, you can provide a form element named \*(L"x\-tunneled-method\*(R" which
can override the request method for a \s-1POST\s0. This \fIonly\fR works for a \s-1POST\s0, not
a \s-1GET\s0.
.PP
You can also use a header named \*(L"x\-http-method-override\*(R" instead (Google uses
this header for its APIs).
.ie n .SS "$request\->looks_like_browser"
.el .SS "\f(CW$request\fP\->looks_like_browser"
.IX Subsection "$request->looks_like_browser"
This attribute provides a heuristic to determine whether or not the request
\&\fIappears\fR to come from a browser. You can use this however you want. I
usually use it to determine whether or not to give the client a full \s-1HTML\s0 page
or some sort of serialized data.
.PP
This is a heuristic, and like any heuristic, it is probably wrong
sometimes. Here is how it works:
.IP "\(bu" 4
If the request includes a header \*(L"X\-Request-With\*(R" set to either \*(L"\s-1HTTP\s0.Request\*(R"
or \*(L"XMLHttpRequest\*(R", this returns false. The assumption is that if you're
doing \s-1XHR\s0, you don't want the request treated as if it comes from a browser.
.IP "\(bu" 4
If the client makes a \s-1GET\s0 request with a query string parameter
\&\*(L"content-type\*(R", and that type is \fInot\fR an \s-1HTML\s0 type, it is \fInot\fR a browser.
.IP "\(bu" 4
If the client provides an Accept header which includes \*(L"*/*\*(R" as an accepted
content type, the client is a browser. Specifically, it is \s-1IE7\s0, which submits
an Accept header of \*(L"*/*\*(R". \s-1IE7\s0's Accept header does not include any html types
like \*(L"text/html\*(R".
.IP "\(bu" 4
If the client provides an Accept header and accepts either \*(L"text/html\*(R" or
\&\*(L"application/xhtml+xml\*(R" it is a browser.
.IP "\(bu" 4
If it provides an Accept header of any sort, it is \fInot\fR a browser.
.IP "\(bu" 4
The default is that the client is a browser.
.PP
This all works well for my apps, but read it carefully to make sure it meets
your expectations before using it.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky, \f(CW\*(C`<autarch@urth.org>\*(C'\fR
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-catalyst\-action\-rest@rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org>. We 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 2008\-2010 Dave Rolsky, All Rights Reserved.
.PP
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.