The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Scaffold-0.10
River stage zero No dependents
/ Scaffold::Handler

NAME

Scaffold::Handler - The base class for Scaffold Handlers

SYNOPSIS

 use Scaffold::Server;

 my $server = Scaffold::Server->new(
    locations => [
        {
            route   => qr{^/$},
            handler => 'App::Main'
        },{
            route   => qr{^/something/(\w+)/(\d+)$},
            handler => 'App::Something'
        }
    ]
 );

 ...

 package App::Main;

 use Scaffold::Class
   version => '0.01',
   base    => 'Scaffold::Handler',
   filesystem => 'File',
 ;

 sub do_main
     my ($self) = @_;

    $self->view->template_disable(1);
    $self->view->data('<p>Hello World</p>');

 }

 1;

 package App::Something;

 use Scaffold::Class
   version => '0.01',
   base    => 'Scaffold::Handler',
   filesystem => 'File',
 ;

 sub do_main
     my ($self, $action, $id) = @_;

    my $text = sprintf("action = %s, id = %s\n", $action, $id);

    $self->view->template_disable(1);
    $self->view->data($text);

 }

 1;

DESCRIPTION

This is the base class for all handlers within Scaffold. Your application will inherit and extend this class. Handlers are the basis of your application.

The Request Lifecycle

When a request comes into Scaffold it is first processed by Scaffold::Server which takes the incomming url and passes it to Scaffold::Routes. Scaffold::Routes parses the url depending on the regex from the "route" verbs in the "locations" stanzia of the configuration. If a match is found it returns the "handler" associated with the route and any parameters extracted from the url. The server then calls the handler's handler() method passing the parameters in @_;

Plugins

Scaffold handlers have an internal state machine. At certain steps, plugins are called. Scaffold loads three plugins at startup. They are Scaffold::Cache::Manager, Scaffold::Session::Manager and Scaffold::Stash::Manager. These plugins help maintain the Scaffold environment. Plugins are guranteed to run in the order they are defined.

The State Machine

The following are the steps that the state machine performs.

pre_action

Plugins are called during this phase. For example Scaffold::Cache::Manager and Scaffold::Session::Manager run in this phase.

action

Your main line code is called during this phase. Please see below to understand how it is called.

post_action

Plugins are called during this phase.

pre_render

Plugins are called during this phase.

render

Your defined render is called to process items in the view stash.

post_render

Plugins are called during this phase.

pre_exit

Plugins are called during this phase. For example Scaffold::Stash::Manager and Scaffold::Session::Manager run during this phase. This is also the last phase before the response is returned back to Scaffold::Server.

The Action Phase

The action phase is where your mainline application code is called. During this phase one of three options can happen. They are the following.

Option 1

If any parameters where extracted from the url, the first one is assumed to be the method that will be called in the handler. This paramenter is then prepended with "do_" and is checked with can() to see if it is defined. If the method is defined it is called with the remaining parameters passed in @_;

Option 2

If the above method is not defined then "do_main" is checked for with can(). If it is defined, it is called with all the parameters passed in @_.

Option 3

If "do_main" is not defined then "do_default" is checked for with can(). If it is defined, it is called with all the parameters passed in @_. If it doesn't exist an exception is thrown and a nice error page is displayed.

Extending and Overriding

Since Scaffold::Handler is inherited, you can override any of the methods that the default handler defines. For example you can override the exceptions() method to handle your applications exceptions.

Where's the MVC

Scaffold handlers don't enforce the MVC pattern. You can certainly write your code in that fashion. There is nothing stopping you. The handler can be considered the controller, the render phase could be considered the view, all you would have to do is create the model. Remember, Scaffold is about flexiablity, not comformity to predefined methodolgies.

METHODS

The following are the methods that you inherit from Scaffold::Handler.

handler(sobj, ref(handler) params)

The main entry point. This method contains the state machine that handles the life cycle of a request. It runs the plugins sends the output thru a renderer for format and returns the response back to the dispatcher.

redirect(url)

The method performs a 302 redirect with the specified URL. A fully qualified URL is returned in the response header.

 $self->redirect('/login');

Redirects are considered exceptions. When one is generated normal processing stops and the redirect happens. Since 3xx level http codes are handled directly by the browser, this method is a prime candiate to override in a single page JavaScript application. In that case it may return a data structure that has meaning to the JavaScript application.

moved_permanently(url)

The method performs a 301 redirect with the specified URL. A fully qualified URL is returned in the response header.

 $self->moved_permanently('/login');

This is considered an exception and normal processing stops.

declined()

This method performs a 404 response, along with an error page. The error page shows the location and the handler that was supposed to run along with a dump of various objects within Scaffold.

 $self->declined();

This is considered an exception and normal processing stops.

not_found(file)

This method performs a 404 response, along with an error page. The error page shows the name of the file that was not found along with a dump of various objects within Scaffold.

 $self->not_found($file);

This is considered an exception and normal processing stops.

exceptions()

This method performs exception handling. The methods redirect(), moved_permanently(), declined() and not_found() throw exceptions. They are handled here. If other exception types need to be handled, this method can be overridden.

SEE ALSO

 Scaffold
 Scaffold::Base
 Scaffold::Cache
 Scaffold::Cache::FastMmap
 Scaffold::Cache::Manager
 Scaffold::Cache::Memcached
 Scaffold::Class
 Scaffold::Constants
 Scaffold::Engine
 Scaffold::Handler
 Scaffold::Handler::Default
 Scaffold::Handler::Favicon
 Scaffold::Handler::Robots
 Scaffold::Handler::Static
 Scaffold::Lockmgr
 Scaffold::Lockmgr::KeyedMutex
 Scaffold::Lockmgr::UnixMutex
 Scaffold::Plugins
 Scaffold::Render
 Scaffold::Render::Default
 Scaffold::Render::TT
 Scaffold::Routes
 Scaffold::Server
 Scaffold::Session::Manager
 Scaffold::Stash
 Scaffold::Stash::Controller
 Scaffold::Stash::Cookie
 Scaffold::Stash::Manager
 Scaffold::Stash::View
 Scaffold::Uaf::Authenticate
 Scaffold::Uaf::AuthorizeFactory
 Scaffold::Uaf::Authorize
 Scaffold::Uaf::GrantAllRule
 Scaffold::Uaf::Login
 Scaffold::Uaf::Logout
 Scaffold::Uaf::Manager
 Scaffold::Uaf::Rule
 Scaffold::Uaf::User
 Scaffold::Utils

AUTHOR

Kevin L. Esteb, <kevin@kesteb.us>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Kevin L. Esteb

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.5 or, at your option, any later version of Perl 5 you may have available.