/ 
Helix-Driver-Router-Basic-0.02
/ Helix::Driver::Router::Basic

NAME

Helix::Driver::Router::Basic - basic request router for Helix Framework.

SYNOPSIS

Somewhere in application controllers:

my $r = Helix::Core::Registry->get_instance;
my $router = $r->loader->get_object("Helix::Driver::Router::Basic");

print "Controller: " . $router->{"controller"}              . "\n";
print "Handler: "    . $router->{"handler"}                 . "\n";
print "Parameters: " . join(", ", @{ $router->{"params"} }) . "\n";

DESCRIPTION

The Helix::Driver::Router::Basic driver finds handler for each user request. Routing is based on controller names and method attributes.

Routing flow

  • Query parsing

    First, this package parses query GET-parameter value. This string is splitted by / character and results are placed to so called query array.

  • Searching controller

    Each part of query array is sequentally checked if it has got a corresponding directory or file in lib/Example/Controller/ directory (Example here should be substituted with your application name). For example, the query was /it/is/full/of/stars/. So, on this step router checks if lib/Example/Controller has one of this files: It.pm, It/Is.pm, It/Is/Full.pm, It/Is/Full/Of.pm, It/Is/Full/Of/Stars.pm, sequentally.

    While query array correlates file system structure, router keeps searching, but when query array item mismatches directory structure, it stops and makes final controller path. For example, if router stopped at It/Is/Full.pm, the final controller path will be Example::Controller::It::Is::Full.

    If the router stopped after realising that It.pm file doesn't exist - it tries to use fallback (default) page instead (lib/Example/Controller/Default.pm).

    The rest of query array is used during the next step.

  • Searching handler

    Here router tries to load selected controller, and if any error occurs, throws an "HXError::Core::Compile" in Helix::Core::Exceptions exception. Then, it makes an action string from the rest of query array by joining it with / character as a glue. For example, if query array contained "full", "of", "stars", the action becomes full/of/stars. Now router checks every method in selected controller if it has got the Action($re) code attribute with $re regular expression, that matches selected action. If regex matches, this method is what router needs.

    If a regular expression contains elements enclosed in round braces (), these elements assumed to be method parameters.

    If action is empty (no elements in the query array), router tries to use a method with Default code attribute.

    After handler was found, router checks its security policy. If application was defined as a private in configuration (see Helix::Core::Config for more information) and a handler doesn't have Public code attribute - "HXError::Driver::Router::Forbidden" in Helix::Driver::Router::Exceptions exception is thrown. Also, this exception is thrown if a handler has got a Private code attribute, without application configuration dependencies.

    If router doesn't find a matching method, "HXError::Driver::Router::NotFound" in Helix::Driver::Router::Exceptions exception is thrown.

Method attributes

Method attributes used to show router which method is responsible for which query. These attributes can combine, i.e. Default attribute could be mixed with Action and access attributes to extend query coverage that is handled by this method.

  • Default

    Routing attribute. Specifies the default page of the controller. It will be called if no action is defined for the controller. Actually, only one Default attribute should exist in one controller, though no one controls this. You can have multiple Default-marked methods in single controller, but which one will be called... only God (and, possibly, Larry) knows.

  • Action("regex")

    Routing attribute. Specifies regular expression that should be matched by query. regex is a usual perl regular expression without starting and ending delimiters. You can use round braces () to specify which parameters you want to be used in method. These parameters could be accessed later (see "params" below).

  • Public

    Security attribute. Specifies that the page that is handled by method should be viewed by anyone, even if application is defined as private.

  • Private

    Security attribute. Specifies that the page that is handled by method should not be viewed by unauthorized user, even if application is defined as public. To make this feature work you need to have at least one user driver installed and this driver should be loaded.

METHODS

new()

Inherited from "new()" in Helix::Driver::Router.

find_handler()

Implementation of abstract method from "find_handler()" in Helix::Driver::Router.

get_handler()

Inherited from "get_handler()" in Helix::Driver::Router.

get_params()

Inherited from "get_params()" in Helix::Driver::Router.

SEE ALSO

Helix, Helix::Applicaton, Helix::Driver::Router

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Anton Belousov, <abel@cpan.org>

COPYRIGHT

Copyright (c) 2009, Atma 7, http://www.atma7.com