Gantry::Engine::CGI(3)

NAME
Gantry::Engine::CGI - CGI plugin ( or mixin )

SYNOPSIS
 use strict;
 use CGI::Carp qw(fatalsToBrowser);
 use MyApp qw( -Engine=CGI -TemplateEngine=Default );
 use Gantry::Engine::CGI;

 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',
   }
 } );

 # optional: templating variables
 $cgi->add_config( 'template_wrapper', 'wrapper.tt' );
 $cgi->add_config( 'root', '/home/httpd/templates' );

 # optional: database connection variables
 $cgi->add_config( 'dbconn', 'dbi:Pg:dbname=mydatabase' );
 $cgi->add_config( 'dbuser','apache' );

 # optional: add another location
 $cgi->add_location( '/music/artists', 'MyApp::Music::Artists' );

 # Standard CGI
 $cgi->dispatch;

 # Fast-CGI
 use FCGI;
 my $request = FCGI::Request();

 while( $request->Accept() >= 0 ) {
   $cgi->dispatch;
 }

Fast-CGI
Be sure add the nesscessary while loop around the cgi dispatch method call.

 use FCGI;
 my $request = FCGI::Request();

 while( $request->Accept() >= 0 ) {
   $cgi->dispatch;
 }

Fast-CGI and Apache
To enable Fast-CGI for Apache goto http://www.fastcgi.com/

 Alias /cgi-bin/ "/home/httpd/cgi-bin/"
 <Location /cgi-bin>
     Options +ExecCGI
     AddHandler fastcgi-script cgi
 </Location>

DESCRIPTION
This module is the binding between the Gantry framework and the CGI API. This particluar module contains the standard CGI specific bindings.

METHODS of this CLASS

new cgi object that can be used to dispatch request to corresonding

dispatch
    This method dispatchs the current request to the corresponding module.

add_config
    Adds a configuration item to the cgi object

add_location
    Adds a location to the cgi object

$self->parse_env
    Used internally. Destroys posted form data.

    Places all query string and form parameters into a hash, which it returns by reference.

METHODS MIXED into the SITE OBJECT

$self->apache_param_hash
    Returns the hash reference of form and query string params.

$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.

$self->base_server
    Returns the physical server this connection came in on (main server or vhost):

$self->cast_custom_error
    Delivers error output to the browser.

$self->cgi_obj
    Dual accessor for the CGI::Simple object.

$self->config
    Dual accessor for updating the config hash in the CGI engine object.

$self->consume_post_body
    This method is for plugins to use at the pre_init phase to catch XML requests and the like. It is imcompatible with normal form processing. For example Gantry::Plugins::SOAP::Doc uses it.

$self->declined_response
    Returns the proper numerical code for DECLINED response.

$self->dispatch_location
    The uri tail specific to this request. Returns:

        $ENV{ PATH_INFO }, $self->config->location

    Note that this a two element list.

$self->engine
    Returns the name for the engine

engine_init
    For use during site object init, by Gantry.pm.

err_header_out
    Does nothing, but meet the engine API.

$self->fish_config
    Pass this method the name of a conf parameter you need. Returns the value for the parameter.

$self->fish_location
    Returns the location for the current request.

$self->fish_method
    Returns the HTTP method of the current request.

$self->fish_path_info
    Returns the path info for the current request.

$self->fish_uri
    Returns the uri for the current request.

$self->fish_user
    Returns the currently logged-in user.

$self->get_arg_hash
    returns a hash of url arguments.

    /some/where?arg1=don&arg2=johnson

$self->get_auth_dbh
    Returns the auth db handle (if there is one).

$self->get_cached_config
    You should normally call get_config instead of this.

    Used internally to store the config hash for a full page hit cycle.

$self->get_config
    If you are using Gantry::Conf, this will return the config hash reference for the current location.

$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.

$self->get_dbh
    Returns the db handle (if there is one).

$self->get_post_body
    Returns whatever "consume_post_body" took from the post body. Use this if you also use a plugin that consumes the post body like Gantry::Plugins::SOAP::Doc does.

$self->header_in
    Does nothing but meet the engine API. mod_perl engines use this.

$self->header_out( $header_key, $header_value )
    Deprecated, merely calls response_headers (defined in Gantry.pm) for you, which you should have done yourself.

    Change the value of a response header, or create a new one.

$self->hostname
    Returns the current host name from the HTTP_SERVER or the HTTP_HOST environment variables. HTTP_SERVER takes precedence.

$self->is_status_declined
    Returns true if the current status is DECLINED, or false otherwise.

$self->log_error
    Prints text to STDERR so you can do the same thing under mod_perl without code changes.

$self->locations
    Dual accessor for the locations hash passed to the constructor or built up with add_location.

$self->remote_ip
    Returns the IP address for the remote user

$self->port
    Returns port number in which the request came in on.

$self->print_output
    Prints whatever you pass to it.

$self->redirect_response
    Prints a redirection to the current header_out location.

$self->send_error_output
    Prints an error header and passes the value of $@ to custom_error.

$self->send_http_header
    Prints the header for the current content_type.

$self->server_root
    Returns the value set by the top-level ServerRoot directive

$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.

$self->set_content_type
    You should use the dual accessor content_type supplied by Gantry.pm.

    This method does nothing except meet the API. mod_perl engines use this to move the content type from the site object to the request object.

$self->set_no_cache
    You should use the dual accessor no_cache supplied by Gantry.pm instead of this.

    Transfers the no_cache flag from the site object to the cgi object.

$self->set_req_params
    Used by Gantry during site object init to transfer params from the cgi engine object to the site object.

$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.

$self->success_code
    Does nothing but meet the engine API. mod_perl engines use it to report the numerical success code.

$self->file_upload
    Uploads a file from the client's disk.

    Parameter: The name of the file input element on the html form.

    Returns: A hash with these keys:

    unique_key
        a unique identifier for this upload

    name
        the base name of the file

    suffix
        the extension (file type) of the file

    fullname
        name.suffix

    size
        bytes in file

    mime
        mime type of file

    filehandle
        a handle you can read the file from

SEE ALSO
Gantry(3)

LIMITATIONS

AUTHOR
Tim Keefer <tkeefer@gmail.com>

COPYRIGHT and LICENSE
Copyright (c) 2005-6, Tim Keefer.

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.