.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "Gantry::Engine::CGI 3"
.TH Gantry::Engine::CGI 3 "2008-01-18" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Gantry::Engine::CGI \- CGI plugin ( or mixin )
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\& use strict;
\& use CGI::Carp qw(fatalsToBrowser);
\& use MyApp qw( -Engine=CGI -TemplateEngine=Default );
\& use Gantry::Engine::CGI;
.Ve
.PP
.Vb 11
\& my $cgi = Gantry::Engine::CGI->new( {
\&   locations => {
\&     '/'        => 'MyApp',
\&     '/music'  => 'MyApp::Music',
\&   },
\&   config => {
\&      img_rootp           => '/malcolm/images',
\&      css_rootp           => '/malcolm/style',
\&      app_rootp           => '/cgi-bin/theworld.cgi',
\&   }
\& } );
.Ve
.PP
.Vb 3
\& # optional: templating variables
\& $cgi->add_config( 'template_wrapper', 'wrapper.tt' );
\& $cgi->add_config( 'root', '/home/httpd/templates' );
.Ve
.PP
.Vb 3
\& # optional: database connection variables
\& $cgi->add_config( 'dbconn', 'dbi:Pg:dbname=mydatabase' );
\& $cgi->add_config( 'dbuser','apache' );
.Ve
.PP
.Vb 2
\& # optional: add another location
\& $cgi->add_location( '/music/artists', 'MyApp::Music::Artists' );
.Ve
.PP
.Vb 2
\& # Standard CGI 
\& $cgi->dispatch;
.Ve
.PP
.Vb 3
\& # Fast-CGI
\& use FCGI;
\& my $request = FCGI::Request();
.Ve
.PP
.Vb 3
\& while( $request->Accept() >= 0 ) {
\&   $cgi->dispatch;
\& }
.Ve
.SH "Fast-CGI"
.IX Header "Fast-CGI"
Be sure add the nesscessary while loop around the cgi dispatch method call.
.PP
.Vb 2
\& use FCGI;
\& my $request = FCGI::Request();
.Ve
.PP
.Vb 3
\& while( $request->Accept() >= 0 ) {
\&   $cgi->dispatch;
\& }
.Ve
.SH "Fast-CGI and Apache"
.IX Header "Fast-CGI and Apache"
To enable Fast-CGI for Apache goto http://www.fastcgi.com/
.PP
.Vb 5
\& Alias /cgi-bin/ "/home/httpd/cgi-bin/"
\& <Location /cgi-bin>
\&     Options +ExecCGI
\&     AddHandler fastcgi-script cgi
\& </Location>
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is the binding between the Gantry framework and the \s-1CGI\s0 \s-1API\s0.
This particluar module contains the standard \s-1CGI\s0 specific bindings. 
.SH "METHODS of this CLASS"
.IX Header "METHODS of this CLASS"
.IP "new" 4
.IX Item "new"
cgi object that can be used to dispatch request to corresonding
.IP "dispatch" 4
.IX Item "dispatch"
This method dispatchs the current request to the corresponding module.
.IP "add_config" 4
.IX Item "add_config"
Adds a configuration item to the cgi object
.IP "add_location" 4
.IX Item "add_location"
Adds a location to the cgi object
.IP "$self\->parse_env" 4
.IX Item "$self->parse_env"
Used internally.  Destroys posted form data.
.Sp
Places all query string and form parameters into a hash, which it returns
by reference.
.SH "METHODS MIXED into the SITE OBJECT"
.IX Header "METHODS MIXED into the SITE OBJECT"
.IP "$self\->apache_param_hash" 4
.IX Item "$self->apache_param_hash"
Returns the hash reference of form and query string params.
.IP "$self\->apache_request" 4
.IX Item "$self->apache_request"
This method does nothing.  It is here to conform the engine api.  mod_perl
engines return their apache request object in response to this method.
.IP "$self\->base_server" 4
.IX Item "$self->base_server"
Returns the physical server this connection came in 
on (main server or vhost):
.IP "$self\->cast_custom_error" 4
.IX Item "$self->cast_custom_error"
Delivers error output to the browser.
.IP "$self\->cgi_obj" 4
.IX Item "$self->cgi_obj"
Dual accessor for the CGI::Simple object.
.IP "$self\->config" 4
.IX Item "$self->config"
Dual accessor for updating the config hash in the \s-1CGI\s0 engine object.
.IP "$self\->consume_post_body" 4
.IX Item "$self->consume_post_body"
This method is for plugins to use at the pre_init phase to catch \s-1XML\s0
requests and the like.  It is imcompatible with normal form processing.
For example Gantry::Plugins::SOAP::Doc uses it.
.IP "$self\->declined_response" 4
.IX Item "$self->declined_response"
Returns the proper numerical code for \s-1DECLINED\s0 response.
.IP "$self\->dispatch_location" 4
.IX Item "$self->dispatch_location"
The uri tail specific to this request.  Returns:
.Sp
.Vb 1
\&    $ENV{ PATH_INFO }, $self->config->location
.Ve
.Sp
Note that this a two element list.
.IP "$self\->engine" 4
.IX Item "$self->engine"
Returns the name for the engine
.IP "engine_init" 4
.IX Item "engine_init"
For use during site object init, by Gantry.pm.
.IP "err_header_out" 4
.IX Item "err_header_out"
Does nothing, but meet the engine \s-1API\s0.
.IP "$self\->fish_config" 4
.IX Item "$self->fish_config"
Pass this method the name of a conf parameter you need.  Returns the
value for the parameter.
.IP "$self\->fish_location" 4
.IX Item "$self->fish_location"
Returns the location for the current request.
.IP "$self\->fish_method" 4
.IX Item "$self->fish_method"
Returns the \s-1HTTP\s0 method of the current request.
.IP "$self\->fish_path_info" 4
.IX Item "$self->fish_path_info"
Returns the path info for the current request.
.IP "$self\->fish_uri" 4
.IX Item "$self->fish_uri"
Returns the uri for the current request.
.IP "$self\->fish_user" 4
.IX Item "$self->fish_user"
Returns the currently logged-in user.
.IP "$self\->get_arg_hash" 4
.IX Item "$self->get_arg_hash"
returns a hash of url arguments.
.Sp
/some/where?arg1=don&arg2=johnson
.IP "$self\->get_auth_dbh" 4
.IX Item "$self->get_auth_dbh"
Returns the auth db handle (if there is one).
.IP "$self\->get_cached_config" 4
.IX Item "$self->get_cached_config"
You should normally call get_config instead of this.
.Sp
Used internally to store the config hash for a full page hit cycle.
.IP "$self\->get_config" 4
.IX Item "$self->get_config"
If you are using Gantry::Conf, this will return the config hash reference
for the current location.
.IP "$self\-> get_cached_conf/set_cached_conf" 4
.IX Item "$self-> get_cached_conf/set_cached_conf"
These cache the Gantry::Conf config hash in a lexical hash.  Override them if
you want more persistent caching.  These are instance methods.  get
receives the invoking object, the name of the GantryConfInstance,
and the current location (for ease of use, its also in the invocant).
set receives those plus the conf hash it should cache.
.IP "$self\->get_dbh" 4
.IX Item "$self->get_dbh"
Returns the db handle (if there is one).
.IP "$self\->get_post_body" 4
.IX Item "$self->get_post_body"
Returns whatever \f(CW\*(C`consume_post_body\*(C'\fR took from the post body.  Use this
if you also use a plugin that consumes the post body like
Gantry::Plugins::SOAP::Doc does.
.IP "$self\->header_in" 4
.IX Item "$self->header_in"
Does nothing but meet the engine \s-1API\s0.  mod_perl engines use this.
.ie n .IP "$self\->header_out( $header_key\fR, \f(CW$header_value )" 4
.el .IP "$self\->header_out( \f(CW$header_key\fR, \f(CW$header_value\fR )" 4
.IX Item "$self->header_out( $header_key, $header_value )"
Deprecated, merely calls response_headers (defined in Gantry.pm)
for you, which you should have done yourself.
.Sp
Change the value of a response header, or create a new one.
.IP "$self\->hostname" 4
.IX Item "$self->hostname"
Returns the current host name from the \s-1HTTP_SERVER\s0 or the \s-1HTTP_HOST\s0
environment variables.  \s-1HTTP_SERVER\s0 takes precedence.
.IP "$self\->is_status_declined" 4
.IX Item "$self->is_status_declined"
Returns true if the current status is \s-1DECLINED\s0, or false otherwise.
.IP "$self\->log_error" 4
.IX Item "$self->log_error"
Prints text to \s-1STDERR\s0 so you can do the same thing under mod_perl
without code changes.
.IP "$self\->locations" 4
.IX Item "$self->locations"
Dual accessor for the locations hash passed to the constructor
or built up with add_location.
.IP "$self\->remote_ip" 4
.IX Item "$self->remote_ip"
Returns the \s-1IP\s0 address for the remote user
.IP "$self\->port" 4
.IX Item "$self->port"
Returns port number in which the request came in on.
.IP "$self\->print_output" 4
.IX Item "$self->print_output"
Prints whatever you pass to it.
.IP "$self\->redirect_response" 4
.IX Item "$self->redirect_response"
Prints a redirection to the current header_out location.
.IP "$self\->send_error_output" 4
.IX Item "$self->send_error_output"
Prints an error header and passes the value of $@ to custom_error.
.IP "$self\->send_http_header" 4
.IX Item "$self->send_http_header"
Prints the header for the current content_type.
.IP "$self\->server_root" 4
.IX Item "$self->server_root"
Returns the value set by the top-level ServerRoot directive
.IP "$self\->set_cached_config" 4
.IX Item "$self->set_cached_config"
For internal use only.  Stores the conf hash from Gantry::Conf so it
doesn't have to be refetched during a single page hit.
.IP "$self\->set_content_type" 4
.IX Item "$self->set_content_type"
You should use the dual accessor content_type supplied by Gantry.pm.
.Sp
This method does nothing except meet the \s-1API\s0.  mod_perl engines use this
to move the content type from the site object to the request object.
.IP "$self\->set_no_cache" 4
.IX Item "$self->set_no_cache"
You should use the dual accessor no_cache supplied by Gantry.pm instead
of this.
.Sp
Transfers the no_cache flag from the site object to the cgi object.
.IP "$self\->set_req_params" 4
.IX Item "$self->set_req_params"
Used by Gantry during site object init to transfer params from the cgi
engine object to the site object.
.IP "$self\->status_const( '\s-1OK\s0 | \s-1DECLINED\s0 | \s-1REDIRECT\s0' )" 4
.IX Item "$self->status_const( 'OK | DECLINED | REDIRECT' )"
Get or set the reply status for the client request. The Apache::Constants 
module provide mnemonic names for the status codes.
.IP "$self\->success_code" 4
.IX Item "$self->success_code"
Does nothing but meet the engine \s-1API\s0.  mod_perl engines use it to report
the numerical success code.
.IP "$self\->file_upload" 4
.IX Item "$self->file_upload"
Uploads a file from the client's disk.
.Sp
Parameter: The name of the file input element on the html form.
.Sp
Returns: A hash with these keys:
.RS 4
.IP "unique_key" 4
.IX Item "unique_key"
a unique identifier for this upload
.IP "name" 4
.IX Item "name"
the base name of the file
.IP "suffix" 4
.IX Item "suffix"
the extension (file type) of the file
.IP "fullname" 4
.IX Item "fullname"
name.suffix
.IP "size" 4
.IX Item "size"
bytes in file
.IP "mime" 4
.IX Item "mime"
mime type of file
.IP "filehandle" 4
.IX Item "filehandle"
a handle you can read the file from
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIGantry\fR\|(3)
.SH "LIMITATIONS"
.IX Header "LIMITATIONS"
.SH "AUTHOR"
.IX Header "AUTHOR"
Tim Keefer <tkeefer@gmail.com>
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (c) 2005\-6, Tim Keefer.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.8.6 or,
at your option, any later version of Perl 5 you may have available.