Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Gantry(3)	      User Contributed Perl Documentation	     Gantry(3)

NAME
       Gantry -	Web application	framework for mod_perl,	cgi, etc.

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
       Note, if	you want to know how to	use Gantry, you	should probably	start
       by reading Gantry::Docs::QuickStart or Gantry::Docs::Tutorial.

       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
       perl(3),	httpd(3), mod_perl(3)

LIMITATIONS
       Limitations are listed in the modules they apply	to.

JOIN US
       Please visit http://www.usegantry.org for project information, sample
       applications, documentation and mailing list subscription instructions.

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

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

       IRC: #gantry on irc.slashnet.org

AUTHOR
       Tim Keefer <tkeefer@gmail.com>

       Phil Crow <philcrow2000@yahoo.com>

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

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.

perl v5.24.1			  2017-07-02			     Gantry(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | MODULES | SEE ALSO | LIMITATIONS | JOIN US | AUTHOR | COPYRIGHT and LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Gantry&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help