NAME

SYNOPSIS

 use Gantry qw/-Engine=MP13 -TemplateEngine=Default/;
 use Gantry qw/-Engine=MP13 -TemplateEngine=TT/;
 use Gantry qw/-Engine=CGI  -TemplateEngine=TT/;
 use Gantry qw/-Engine=MP20/;

DESCRIPTION

Perl Web application framework for Apache/mod_perl. Object Oriented design for a pragmatic, modular approach to URL dispatching. Supports MVC (or VC, MC, C, take your pick) and initiates rapid development. This project offers an orgainized coding scheme for web applications.

Gantry can be extended via plugins. The plugins can optionally contain callback methods.

Defined phases where callbacks can be assigned. pre_init at the beginning, before pretty much everything post_init just after the main initializtion of the request pre_action just before the action is processed post_action just after the action has been processed pre_process just before the template engine is envoked post_process right after the template engine has done its thing

 package Gantry::Plugins::SomePlugin;

 sub get_callbacks {
     my ( $class, $namespace ) = @_;

     return if ( $registered_callbacks{ $namespace }++ );

     return (
         { phase => 'init',      callback => \&initialize },
         { phase => 'post_init', callback => \&auth_check },
     );
 }
 
 sub initialize {
     my $gantry_site_object = shift;
     ...
 }
 
 sub auth_check {
     my $gantry_site_object = shift;
     ...
 }

 Note that the pre_init callback receives an additional parameter which
 is either the request object (for mod_perl) or the CGI object.

 If your plugin in registers callbacks, please document this for your users.
 They should add -PluginNamespace to the full use list, and it must come
 before the plugins which register callbacks. In addition, you can
 specify a plugin location with -PluginDir. This allows you to put
 plugins in directories out outside of the default Gantry::Plugins directory.
 
 Plugin callbacks are called in the order in which the plugins are loaded.
 This gives you some control over the order in which the callbacks will run
 by controlling the order in which the plugins are specified in the application
 use statement.
 
 Example:

     use Some::Gantry::App qw(
         -Engine=MP20
         -Template=TT
         -PluginNamespace=module_name
         SOAPMP20
         -PluginDir=MyApp::Plugins
         MyPlugin
     );

 Then, they should implement a method called namespace at the top of each
 heirarchy which needs the plugins:

     sub namespace { return 'module_name'; }

METHODS

handler

This is the default handler that can be inherited it calls init, and cleanup. Methods to be called from this handler should be of the naming convention do_name. If this cannot be found then the autoloader is called to return declined. Methods should take $r, and any other parameters that are in the uri past the method name.

init

The init is called at the begining of each request and sets values such as, app_rootp, img_rootp, and other application set vars.

declined

 $self->declined( 1 );
    

Set and unset the declined flag

relocate

 $self->relocate( location );
    

This method can be called from any controller will relocated the user to the given location.

This method has been moved to Gantry::State::Default.

relocate_permanently

 $self->relocate_permanently( location );
    

This method can be called from any controller will relocated the user to the given location using HTTP_MOVED_PERMANENTLY 301.

This method has been moved to Gantry::State::Default.

redirect

 $self->redirect( 1 );
    

Set and unset the redirect flag

no_cache

 $self->no_cache( 1 );
    

Set and unset the no cache flag. This directive informs Apache to either send the the no_cache header or not.

gantry_response_page

Dual use accessor for caching page content. If a plugin prior to the action phase populates this value, that value will be directly returned to the browser, no dispatch will occur.

template_disable

 $self->template_disable( 1 );
    

Set and unset the template disable flag.

method

 $self->method;
 $self->method( $r->method );
    

Set/get the apache request method, either 'POST' or 'GET'

cleanroot

 $self->cleanroot( uri, root );
    

Splits the URI and returns and array of the individual path locations.

cleanup

 $self->cleanup
    

This method is called at the end of the request phase to cleanup, disconnect for a database, etc.

icrement_engine_cycle

 $self->_increment_engine_cycle
    

Increments the the engine cycles total.

engine_cycle

 $self->engine_cycle
    

Returns the engine cycle total.

custom_error

Generates an error page. Feel free to override this to change the appearance of the error page.

get_cookies

 $hash_ref_of_cookies = $self->get_cookies();
 $cookie_value = $self->get_cookies( 'key_of_cookie' );
    

If called without any parameters, this method will return a reference to a hash of all cookie data. Otherwise, by passing a key to this method then the value for the requested cookie is returned.

set_cookie

 $self->set_cookie( { 
    name => cookie name,
    value => cookie value,
    expire => cookie expires,
    path => cookie path,
    domain => cookie domain,
    secure => [0/1] cookie secure,
  } )
    

This method can be called repeatedly and it will create the cookie and push it into the response headers.

cookie_stash

Used by set_cookie to store/buffer cookies for the CGI engine. Not intended for direct calls.

response_headers

Dual use accessor.

Parameters: key value

Returns: always returns the hash of headers

Omit the key and value for pure getter behavior.

r - The Apache Request

 $r = $self->r; 
 $self->r( $r );
    

Set/get for apache request object

cgi

 $cgi = $self->cgi; $self->cgi( CGI::Simple->new() );
    

Set/get for CGI::Simple object. See CGI::Simple docs. This method is only available when using the CGI engine.

uri

 $uri = $self->uri; 
 $self->uri( uri );
    

Set/get for server uri

location

 $location = $self->location; 
 $self->location( location );
    

Set/get for server location

current_url

 $url_for_email = $self->current_url
    

Get the url of the current page. This combines protocol, base_server and uri to form a valid url suitable for inclusion in an email.

path_info

 $path_info  = $self->path_info; $self->path_info( path_info );
    

Set/get for server path_info

content_type

 $type = $self->content_type;
 $self->content_type( 'text/html' );
    

Set/get for reponse content-type

content_length

 $type = $self->content_length;
 $self->content_length( $length );
    

Set/get for reponse content-length

root

 $self->root( '/home/tkeefer/myapp/root' );
 $root = $self->root;
    

Set/get for the root value. This value is the application root directory that stores the templates and other application specific files.

template

 $self->template( 'some_template.tt' );
    

Set/get for template name for current request

The filename is relative to the $self->root value, otherwise it needs to be the full path to template file.

template_default

 $self->template_default( 'some_default_template.tt' );
    

Set/get for a template default value. If a template has not been defined for the request, then the default template is called.

The filename is relative to the $self->root value, otherwise it needs to be the full path to template file.

template_wrapper

 $self->template_wrapper( 'wrappers/wrapper.tt' );
    

Set/get for the template toolkit wrapper file. The wrapper does exactly as it says; it wrapper the ouput from the controller before the response is sent to the client.

The filename is relative to the $self->root value, otherwise it needs to be the full path to template file.

status

Dual accessor for the HTTP status of the page hit.

css_root

 $self->css_root( '/home/tkeefer/myapp/root/css' );
 $css_root = $self->css_root;
    

Set/get for the css_root value. This value is used to locate the css files on disk.

img_root

 $self->img_root( '/home/tkeefer/myapp/root/images' );
 $img_root = $self->img_root;
    

Set/get for the img_root value. This value is used to locate the application image files on disk.

doc_root

 $self->doc_root( '/home/tkeefer/myapp/root' );
 $doc_root = $self->doc_root;
    

Set/get for the doc_root value. This value is used to locate the application root directory on disk.

app_rootp

 $self->app_rootp( '/myapp' );
 $app_rootp = $self->app_rootp;
    

Set/get for the app_rootp value. This value is used to identify the the root URI location for the web application.

img_rootp

 $self->img_rootp( '/myapp' );
 $img_rootp = $self->img_rootp;
    

Set/get for the img_rootp value. This value is used to identify the the root URI location for the web application images.

web_rootp

 $self->web_rootp( 'html' );
 $web_rootp = $self->web_rootp;
    

Set/get for the web_rootp value. This value is used to identify the the root URI location for the web files.

doc_rootp

 $self->doc_rootp( 'html' );
 $doc_rootp = $self->doc_rootp;
    

Set/get for the doc_rootp value. This value is used to identify the the root URI location for the web files.

css_rootp

 $self->css_rootp( '/myapp/style' );
 $css_rootp = $self->css_rootp;
    

Set/get for the app_rootp value. This value is used to identify the the root URI location for the web application css files.

tmp_rootp

 $self->tmp_rootp( '/myapp/tmp' );
 $tmp_rootp = $self->tmp_rootp;
    

Set/get for the tmp_rootp value. This value is used to identify the the root URI location for the web application temporary files.

js_rootp

 $self->js_rootp( '/myapp/js' );
 $js_rootp = $self->js_rootp;
    

Set/get for the js_rootp value. This value is used to identify the the root URI location for the web application javascript files.

editor_rootp

 $self->editor_rootp( '/fck' );
 $editor_rootp = $self->editor_rootp;
    

Set/get for the editor_rootp value. This value is used to identify the the root URI location for the html editor.

tmp_root

 $self->tmp_rootp( '/home/httpd/html/myapp/tmp' );
 $tmp_root = $self->tmp_root;
    

Set/get for the tmp_root value. This value is used to identify the the root directory location for the web application temporary files.

js_root

 $self->js_rootp( '/home/httpd/html/myapp/js' );
 $js_root = $self->js_root;
    

Set/get for the js_root value. This value is used to identify the the root directory location for the web application javascript files.

stash

Use this to store things for your template system, etc. See Gantry::Stash.

smtp_host

An obscure accessor for storing smtp_host.

user

 $self->user( $apache_connection_user );
 $user = $self->user;
    

Set/get for the user value. Return the full user name of the active user. This value only exists if the user has successfully logged in.

controller_config

This method is used by the AutoCRUD plugin and others to get code controlled config information, like table permissions for row level auth contro.

The method in this module returns an empty hash, making it safe to call this method from any Gantry subclass. If you want to do anything useful, you need to override this method in your controller.

get_auth_model_name

Always returns Gantry::Control::Model::auth_users. Override this method if you want a different auth model.

set_auth_model_name

Allows you to set the auth model name, but for this to work correctly, you must override get_auth_model_name. Otherwise your get request will always give the default value.

test

 $self->test( 1 );
    

enable testing mode

user_id

 $user_id = $self->user_id( model => '', user_name => '' );
 $user_id = $self->user_id;
    

Returns the user_id for the given user_name or for the currently logged in user, if no user_name parameter is passed. The user_id corresponds to the user_name found in the auth_users table. The user_id is generally used for changelog entries and tracking user activity within an app.

By default, the first time you call user_id or user_row during a request, the model will be set. It will be set to the value you pass in as model or the value returned by calling "<$self-"get_auth_model_name>>, if no model parameter is passed. This module has a get_auth_model_name that always returns 'Gantry::Control::Model::auth_users'. If you use a different model, override get_auth_model_name in your app's base module. We assume that your model has these methods: id and user_name.

user_row

 $user_row = $self->user_row( model => '', user_name '' );
 $user_row = $self->user_row;
    

The same as user_id, but it returns the whole model object (usually a representation of a database row).

If your models are based on DBIx::Class, or any other ORM which does not provide direct search calls on this models, you must implement a search method in your auth_users model like this:

    sub search {
        my ( $class, $search_hash, $site_object, $extra_hash ) = @_;

        my $schema = $site_object->get_schema();

        return $schema->resultset( 'auth_users' )->search(
                $search_hash, $extra_hash
        );
    }
    

user_row calls this method, but DBIx::Class does not provide it for the model. Further, the search it does provide is available through the resultset obtained from the schema. This module knows nothing about schema, but it passes the self object as shown above so you can fish it out of the site object.

page_title

 $self->page_title( 'Gantry is for you' );
 $page_title = $self->page_title;
    

Set/get for the page title value. This page title is passed to the template and used for the HTML page title. This can be set in either the Apache LOCATION block or in the contoller.

date_fmt

 $self->date_fmt( '%m %d, %Y' );
 $fmt = $self->date_fmt;
    

Set/get for the date format value. Used within the application for the default date format display.

post_max

 $self->post_max( '4M' );
 $post_max = $self->post_max;
    

Set/get for the apache request post_max value. See Apache::Request or Apache2::Request docs.

ap_req

 $self->ap_req( api_call_to_apache );
 $req = $self->ap_req;
    

Set/get for the apache request req object. See mod_perl documentation for intructions on how to use apache requets req.

get_param_hash

Always returns the params (from forms and the query string) as a hash (not a hash reference, a real hash).

get_uf_param_hash

Always returns the unfiltered params (from forms and the query string) as a hash (not a hash reference, a real hash).

params

 $self->params( $self->ap_req );
 $params = $self->params;
    

Set/get for the request parameters. Returns a reference to a hash of key value pairs.

uf_params

 $self->uf_params( $self->ap_req );
 $uf_params = $self->uf_params;
    

Set/get for the unfiltered request parameters. Returns a reference to a hash of key value pairs.

serialize_params

 $self->serialize_params( [ array_ref of keys to exclude ], <separator> );
 $self->serialize_params( [ 'page' ], '&' );
    

Returns a serialized string of request parameters. The default separator is '&'

escape_html

  $self->escape_html($value)
    

Replace any unsafe html characters with entities.

unescape_html

  $self->unescape_html($value)
    

Unescape any html entities in the specified value.

protocol

 $self->protocol( $ENV{HTTPS} ? 'https://' : 'http://' );
 $protocol = $self->protocol;
    

Set/get for the request protocol. Value is either 'http://' or 'https://'. This is used to construct the full url to a resource on the local server.

get_conf

Pass this the name of the instance and (optionally) the ganty.conf file where the conf for that instance lives. Returns whatever Gantry::Conf->retrieve returns.

make_stash

For internal use. Makes a new stash. The old one is lost.

trim

For internal use in cleaning up Data::Dumper output for presentation on the default custom_error page.

is_post

returns a true value (1) if client request is of post method.

gantry_secret

Returns the currently configured value of gantry_secret or w3s3cR7 otherwise.

schema_base_class

Not yet implemented. Currently you must code this in your model base class.

Dual use accessor so you can keep track of the base model class name when using DBIx::Class.

namespace

Call this as a class OR object method. Returns the namespace of the current app (which could be the name of the apps base module). The one in this module always returns 'Gantry'.

You need to implement this if you use a plugin that registers callbacks, so those callbacks will only be called for the apps that want the plugin. Otherwise, every app in your Apache server will have to use the plugin, even those that don't need it.

Currently, the only plugin that registers callbacks is AuthCookie.

gantry_version

Returns the current Gantry version number. Like using $Gantry::VERSION but via a method.

action

Returns the name of the current do_ method (like 'do_edit').

MODULES

Gantry::Stash

Main stash object for Gantry

Gantry::Utils::Model

Gantry's native object relational model base class

Gantry::Utils::DBIxClass

DBIx::Class base class for models

Gantry::Plugins::DBIxClassConn

Mixin providing get_schema which returns DBIx::Class::Schema for data models

Gantry::Utils::CDBI

Class::DBI base class for models

Gantry::Plugins::CRUD

Helper for flexible CRUD coding scheme.

Gantry::Plugins::AutoCRUD

provides a more automated approach to CRUD (Create, Retrieve, Update, Delete) support

Gantry::Plugins::Calendar

These module creates a couple calendar views that can be used by other applications and are highly customizeable.

Gantry::Engine::MP13

This module is the binding between the Gantry framework and the mod_perl API. This particluar module contains the mod_perl 1.0 specific bindings.

See mod_perl documentation for a more detailed description for some of these bindings.

Gantry::Engine::MP20

This module is the binding between the Gantry framework and the mod_perl API. This particluar module contains the mod_perl 2.0 specific bindings.

See mod_perl documentation for a more detailed description for some of these bindings.

Gantry::Control

This module is a library of useful access functions that would be used in other handlers, it also details the other modules that belong to the Control tree.

Gantry::Utils::DB

These functions wrap the common DBI calls to Databases with error checking.

Gantry::Template::TT

This is recommended templating system in use by by Gantry.

Gantry::Template::Default

This modules is used to to bypass a tempalting system and used if you prefer to output the raw text from within the controllers.

Gantry::Utils::HTML

Implements HTML tags in a browser non-specfic way conforming to 3.2 and above HTML specifications.

Gantry::Utils::SQL

This module supplies easy ways to make strings sql safe as well as allowing the creation of sql commands. All of these commands should work with any database as they do not do anything database specfic, well as far as I know anyways.

Gantry::Utils::Validate

This module allows the validation of many common types of input.

Gantry::Server

Stand alone web server used for testing Gantry applications and for quick delopment of Gantry applications. This server is not recommended for production use.

Gantry::Conf

Flexible configuration system for Gantry

SEE ALSO

LIMITATIONS

JOIN US

Web: <http://www.usegantry.org>

Mailing List: <http://www.usegantry.org/mailinglists/>

IRC: #gantry on irc.slashnet.org

AUTHOR

Phil Crow <philcrow2000@yahoo.com>

Gantry was branched from Krkit version 0.16 Sat Jun 11 15:27:28 CDT 2005

COPYRIGHT and LICENSE

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.