/ 
Scaffold-0.02
River stage zero No dependents
/ Scaffold::Handler

NAME

Scaffold::Handler - The base class for Scaffold URL handlers

SYNOPSIS

use Scaffold::Server;

my $server = Scaffold::Server->new(
   locations => {
       '/'            => 'App::Main',
       '/robots.txt'  => 'Scaffold::Handler::Robots',
       '/favicon.ico' => 'Scaffold::Handler::Favicon',
       '/static'      => 'Scaffold::Handler::Static',
   },
);

...

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;

DESCRIPTION

There are many ways to dispatch and handle requests for a particular URL. Scaffold does a simple direct mapping of URL to handler. When the dispatch() method in Scaffold::Server is invoked it is passed a Plack::Request object. The object contains the URL of the request. dispatch() will then parse that URL and looks in "locations" for a corresponding handler. If a handler is found, that handlers, handler() method is evoked, which further parses the URL to determine which methods are called within the handler.

So, for example a request to "/" is made. This would evoke the App::Main handler. The handler for App::Main would determine that it should call do_main(). do_main() is always called for the root of a URL. If do_main() doesn't exist then a call to do_default() will be tried. If neither of these methods exist a "declined" exception is thrown.

So, now a request to "/photos' is made. This would also evoke App::Main. Which would determine that it should call the do_photos() method. Since there is none, it would try to evoke do_default() passing "photos" as the first parameter. Since do_default() also doesnt' exist, it will throw a "declined" exception.

Now we add a do_photos() method:

sub do_photos {
    my ($self, $dir, $wanted) = @_;

    my $photo;
    my $file = File($dir, $wanted . '.png');

    if ($file->exists) {

        $photo = $file->read;

        $self->view->data($photo);
        $self->view->template_disable(1);
        $self->view->content_type('image/png');

    } else {

        $self->not_found($file);

    }

}

The method, do_photos() wants two parameters passed to it. They will be parsed out of the URL. So a request to "/photos/family/25" is made. The App::Main handler is called. The do_photos() method is invoked passing "family" and "25" as the two parameters. If the do_photos() method didn't exist and a do_default method did, it would be passed three parameters; "photos", "family" and "25".

Handlers also run plugins. Plugins are envoked at specific times during the request's life cycle. They may be used as filters or to perform specific actions.

METHODS

handler

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

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

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

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::Favicon
Scaffold::Handler::Robots
Scaffold::Handler::Static
Scaffold::Lockmgr
Scaffold::Lockmgr::KeyedMutex
Scaffold::Plugins
Scaffold::Render
Scaffold::Render::Default
Scaffold::Render::TT
Scaffold::Server
Scaffold::Session::Manager
Scaffold::Stash
Scaffold::Stash::Controller
Scaffold::Stash::Cookie
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, <kesteb@wsipc.org>

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.