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:

$controller ( GX::Controller object )

Exceptions:

GX::Exception

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:

$action ( GX::Action object | undef )

`actions`

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

    @actions = $controller->actions;

Returns:

@actions ( GX::Action objects )

`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:

$hook ( GX::Callback::Hook object | undef )

`filter_hooks`

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

    @hooks = $controller->filter_hooks;

Returns:

@hooks ( GX::Callback::Hook objects )

`filters`

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

    @filters = $controller->filters;

Returns:

@filters ( GX::Callback objects )

`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:

@hooks ( GX::Callback::Hook objects )

`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:

@filters ( GX::Callback objects )

`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:

@hooks ( GX::Callback::Hook objects )

`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:

@filters ( GX::Callback objects )

`renderer`

Returns the renderer that is associated with the specified action.

    $renderer = $controller->renderer( $action_name );

Arguments:

$action_name ( string )

Returns:

$renderer ( GX::Renderer object | undef )

`routes`

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

    @routes = $controller->routes;

Returns:

@routes ( GX::Route objects )

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:

GX::Exception

Internal Methods

`dispatch`

Internal method.

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

Arguments:

$context ( GX::Context object )
$action ( GX::Action object )

`handle_error`

Internal method.

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

Arguments:

$context ( GX::Context object )
$error ( GX::Exception object | string )

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

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.

To install GX, copy and paste the appropriate command in to your terminal.

cpanm

cpanm GX

CPAN shell

perl -MCPAN -e shell
install GX

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

Constructor

new

Public Methods

action

actions

base_path

default_format

filter_hook

filter_hooks

filters

name

post_dispatch_filter_hooks

post_dispatch_filters

pre_dispatch_filter_hooks

pre_dispatch_filters

renderer

routes

setup

Internal Methods

dispatch

handle_error

EXAMPLES

Actions

Filters

Routing

Rendering

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions

`new`

`action`

`actions`

`base_path`

`default_format`

`filter_hook`

`filter_hooks`

`filters`

`name`

`post_dispatch_filter_hooks`

`post_dispatch_filters`

`pre_dispatch_filter_hooks`

`pre_dispatch_filters`

`renderer`

`routes`

`setup`

`dispatch`

`handle_error`