NAME
KelpX::Controller - Base custom controller for Kelp
SYNOPSIS
### application's configuration
modules_init => {
Routes => {
base => 'My::Controller',
rebless => 1, # needed for historic reasons
}
},
### your base controller
package My::Controller;
use Kelp::Base 'KelpX::Controller';
sub build
{
my $self = shift;
$self->add_route('/sub' => sub { ... });
$self->add_route('/method_name', 'this_controller_method');
$self->add_route('/hashref', {
to => 'this_controller_method',
});
}
sub this_controller_method
{
my $self = shift;
return 'Hello world from ' . ref $self;
}
### your main application class
package My::Kelp;
attr context_obj => 'KelpX::Controller::Context';
sub build
{
my $self = shift;
$self->context->build_controllers;
}DESCRIPTION
Since Kelp 2.16 it's quite easy to introduce your own base controller class instead of subclassing the main application class.
This extension is a more modern approach to route handling, which lets you have a proper hierarchy of custom classes which serve as controllers. Enabling it is easy, and can be done as shown in "SYNOPSIS".
The controller will be built just like a regular object the first time it's used. It will not be cleared after the request, since the context object will have its persistent_controllers set to true by default. You may override "build" in the controller, but if you want to have it add any routes then you will have to instantiate it manually using $app->context->controller.
Building controllers
In order for routes defined in your controller to register, you need to build the controllers. You can done it manually by calling $self->context->controller for each of your controllers, or automatically by calling $self->context->build_controllers. The latter will load all modules in the namespace of your base controller using Module::Loader and build them. As long as all your controllers are in the same namespace under the base controller, the automatic method is recommended (though it does not allow for conditional disabling of the controllers).
ATTRIBUTES
context
Required. The app's context object.
app
The application object. Will be loaded from "context".
METHODS
These methods are provided for convenience, but they are not meant to fully replicate the API available when not using controllers or using reblessing. For this reason, this module is not a drop-in replacement for reblessing controllers.
build
A build method, which will be called right after the controller is instantiated. Similar to app build method. Takes no arguments and does nothing by default - it's up to you to override it.
Since controllers inherit from one another and each route should only be built once, a special check is implemented which will not run this method automatically if it was not implemented in a controller class (to avoid calling parent class method). Make sure not to call SUPER version of this method if you implement it. If you need code that must be run for every controller, it's recommended to override new.
add_route
Similar to "add_route" in Kelp::Module::Routes, but it modifies the destination so that the route dispatch will run in the context of current controller. Unlike core Kelp controllers, you can use simple function names or even plain subroutines and they will pass the instance of your controller as their first argument.
req
Proxy for reading the req attribute from "context".
res
Proxy for reading the res attribute from "context".
CAVEATS
When using this module, even subroutine based routes will be run using the application's main controller (instead of application instance). Thanks to this, main class will never be used as call context for route handlers, so any hooks like
before_dispatchcan be safely moved to the base controller.
SEE ALSO
AUTHOR
Bartosz Jarzyna, <bbrtj.pro@gmail.com>
COPYRIGHT AND LICENSE
Copyright (C) 2024 by Bartosz Jarzyna
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.