GX::Controller

Module Version: 0.2000_01

NAME

GX::Controller - Controller component

SYNOPSIS

package MyApp::Controller::Root;

use GX::Controller;

sub hello :Action {
my ( $self, $context ) = @_;
$context->response->content_type( 'text/plain' );
$context->response->add( 'Hello World!' );
return;
}

1;

DESCRIPTION

This module provides the GX::Controller component class which extends the GX::Component::Singleton class.

METHODS

Constructor

new

Returns the controller instance.

$controller = $controller_class->new;
Returns:
Exceptions:

Public Methods

All public methods can be called both as instance and class methods.

action

Returns the action object that represents the specified action.

$action = $controller->action( $action_name );
Arguments:
  • $action_name ( string )
Returns:

actions

Returns a list with the action objects that represent the controller's actions.

@actions = $controller->actions;
Returns:

base_path

Returns the controller's base path.

$path = $controller->base_path;
Returns:
  • $path ( string )

    A slash terminated string.

default_format

Returns the default render format.

$format = $controller->default_format;
Returns:
  • $format ( string | undef )

filter_hook

Returns the hook object that represents the specified filter hook.

$hook = $controller->filter_hook( $hook_name );
Arguments:
  • $hook_name ( string )
Returns:

filter_hooks

Returns a list with the hook objects that represent the controller's filter hooks.

@hooks = $controller->filter_hooks;
Returns:

filters

Returns a list with the callback objects the represent the controller's filters.

@filters = $controller->filters;
Returns:

name

Returns the name of the controller.

$name = $controller->name;
Returns:
  • $name ( string )

post_dispatch_filter_hooks

Returns a list with the hook objects that represent the controller's post-dispatch filter hooks in order of execution.

@hooks = $controller->post_dispatch_filter_hooks;
Returns:

post_dispatch_filters

Returns a list with the callback objects the represent the controller's post-dispatch filters in order of execution.

@filters = $controller->post_dispatch_filters;
Returns:

pre_dispatch_filter_hooks

Returns a list with the hook objects that represent the controller's pre-dispatch filter hooks in order of execution.

@hooks = $controller->pre_dispatch_filter_hooks;
Returns:

pre_dispatch_filters

Returns a list with the callback objects the represent the controller's pre-dispatch filters in order of execution.

@filters = $controller->pre_dispatch_filters;
Returns:

renderer

Returns the renderer that is associated with the specified action.

$renderer = $controller->renderer( $action_name );
Arguments:
  • $action_name ( string )
Returns:

routes

Returns a list with the route objects that represent the routes for the controller's actions.

@routes = $controller->routes;
Returns:

This method does not return the effective routes for the controller's actions. See GX::Router for more information.

setup

Sets up the controller.

$controller_class->setup( %options );
Options:
  • auto_render ( bool )

    A boolean flag indicating whether or not to enable automatic rendering. Defaults to true.

  • base_path ( string )

    A custom base path for the controller.

  • create_default_renderers ( bool )

    A boolean flag indicating whether or not to create default renderers. Defaults to true.

  • create_default_routes ( bool )

    A boolean flag indicating whether or not to create default routes. Defaults to true.

  • default_format ( string | undef )

    The default render format. Defaults to "html".

  • inherit_actions ( bool )

    A boolean flag indicating whether the controller should inherit actions from its base classes or not. Defaults to true.

  • inherit_filters ( bool )

    A boolean flag indicating whether the controller should inherit filters from its base classes or not. Defaults to true.

  • render ( HASH reference )

    A reference to a hash with rendering directives for the controller's actions.

  • render_all ( scalar )

    A global rendering directive that is applied to all the controller's actions. Also see the render option.

  • routes ( ARRAY reference | HASH reference )

    A reference to an array or to a hash with route definitions.

Exceptions:

Internal Methods

dispatch

Internal method.

$controller->dispatch( $context, $action );
Arguments:

handle_error

Internal method.

$controller->handle_error( $context, $error );
Arguments:

EXAMPLES

Actions

Example #1

Obligatory "Hello World" example:

sub hello :Action {
my ( $self, $context ) = @_;
$context->response->content_type( 'text/plain' );
$context->response->add( 'Hello World!' );
return;
}

Filters

Example #1

Declaring a pre-dispatch filter using the :Before method attribute:

sub authenticate_client :Before {
my ( $self, $context ) = @_;
if ( $context->request->remote_address ne '127.0.0.1' ) {
$context->send_response( status => 403 );
}
return;
}

Example #2

Declaring a post-dispatch filter using the :After method attribute:

sub log_success :After {
my ( $self, $context ) = @_;
$self->application->log( 'Success!' );
return;
}

Example #3

Declaring a render filter using the :Render method attribute:

sub add_default_message :Render {
my ( $self, $context ) = @_;
$context->response->content_type( 'text/plain' );
$context->response->add( 'Nothing to see here. Move along.' );
return;
}

Routing

Example #1

Declaring simple path-based routes:

MyBlog::Controller::Articles->setup(
routes => [
'home' => '/articles',
'search' => '/articles/search',
'show' => '/articles/archive/{id}'
],
# ...
);

Same as above (assuming the controller's base path is "/articles"):

MyBlog::Controller::Articles->setup(
routes => [
'home' => './',
'search' => './search',
'show' => './archive/{id}'
],
# ...
);

Example #2

Declaring complex routes:

MyBlog::Controller::Articles->setup(
routes => [
'home' => {
path => '/articles'
},
'search' => {
methods => [ 'POST' ],
path => '/articles/search'
},
'show' => {
host => 'myblog.{domain:com|org}',
path => '/articles/archive/{id:\d+}.{format:html|xml}',
defaults => { 'format' => 'html' }
}
],
# ...
);

Example #3

Using the :Action method attribute to declare path-based routes:

sub home :Action( '/articles' ) {
# ...
}

sub search :Action( '/articles/search' ) {
# ...
}

sub show :Action( '/articles/archive/{id}' ) {
# ...
}

Rendering

Example #1

Simple example of the action => format => handler configuration syntax:

MyBlog::Controller::Articles->setup(
render => {
'show' => {
'html' => {
view => 'MyBlog::View::TT',
template => 'articles/show.html.tt'
},
'txt' => {
view => 'MyBlog::View::TT',
template => 'articles/show.txt.tt'
}
},
'search' => {
'html' => {
view => 'MyBlog::View::TT',
template => 'articles/search.html.tt'
}
}
},
# ...
);

Example #2

Specifying a default format handler:

MyBlog::Controller::Articles->setup(
render => {
'error' => {
'*' => {
view => 'MyBlog::View::TT',
template => 'error.html.tt'
}
}
},
# ...
);

Shorthand notation for the above:

MyBlog::Controller::Articles->setup(
render => {
'error' => [ view => 'MyBlog::View::TT', template => 'error.html.tt' ]
},
# ...
);

A default format handler can be combined with one or more specific format handlers:

MyBlog::Controller::Articles->setup(
render => {
'error' => {
'txt' => {
view => 'MyBlog::View::TT',
template => 'error.txt.tt'
},
'xml' => {
view => 'MyBlog::View::TT',
template => 'error.xml.tt'
},
'*' => {
view => 'MyBlog::View::TT',
template => 'error.html.tt'
}
}
},
# ...
);

In that case, the default format handler will handle the rendering of all non-specified formats.

Example #3

Assignment of arbitrary callbacks as format handlers:

MyBlog::Controller::Articles->setup(
render => {
'show' => {
'html' => GX::Callback->new( \&code )
}
},
# ...
);

Example #4

Full low-level control by assigning renderers directly to actions:

MyBlog::Controller::Articles->setup(
render => {
'show' => do {
my $renderer = GX::Renderer->new;
$renderer->handler(
'html' => GX::Callback::Method->new(
invocant => MyBlog::View::TT->instance,
method => 'render',
arguments => [ template => 'articles/show.html.tt' ]
)
);
$renderer->handler(
'txt' => GX::Callback::Method->new(
invocant => MyBlog::View::TT->instance,
method => 'render',
arguments => [ template => 'articles/show.txt.tt' ]
)
);
$renderer;
},
'search' => do {
my $renderer = GX::Renderer->new;
$renderer->handler(
'html' => GX::Callback::Method->new(
invocant => MyBlog::View::TT->instance,
method => 'render',
arguments => [ template => 'articles/search.html.tt' ]
)
);
$renderer;
}
},
# ...
);

AUTHOR

Jörg A. Uzarek <uzarek@runlevelnull.de>

COPYRIGHT AND LICENSE

Copyright © 2009-2011 Jörg A. Uzarek.

This module is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License Version 3 as published by the Free Software Foundation.