From d34738acf10dca1b0faf88d6f3a95c86b1f330b2 Mon Sep 17 00:00:00 2001 From: bbrtj Date: Sat, 6 Jul 2024 05:55:00 +0200 Subject: [PATCH] Documentation improvements --- Changes | 1 + lib/Kelp/Context.pm | 16 +++++---- lib/Kelp/Manual/Controllers.pod | 21 ++++++------ lib/Kelp/Manual/Cookbook.pod | 59 ++++++--------------------------- 4 files changed, 32 insertions(+), 65 deletions(-) diff --git a/Changes b/Changes index 2f402da..c864273 100644 --- a/Changes +++ b/Changes @@ -3,6 +3,7 @@ Revision history for Kelp {{$NEXT}} [Changes] - Fixed psgi routes not working with custom controllers + - Documentation improvements 2.16 - 2024-07-05 [New Interface] diff --git a/lib/Kelp/Context.pm b/lib/Kelp/Context.pm index d5a45a1..ec98a75 100644 --- a/lib/Kelp/Context.pm +++ b/lib/Kelp/Context.pm @@ -131,16 +131,20 @@ Returns a controller of a given name. The name will be mangled according to the base route class of the application. Contains extra checks to ensure the input is valid and loads the controller class if it wasn't loaded yet. -If the controller name is undef, the base controller is returned. +If the controller name is C, the base controller is returned. =head2 set_controller -Like L, but does not have any special checks for correctness and -only accepts a full class name. It also modifies the L to the -controller after constructing it. It's optimized for speed and used only -internally. +Similar to L, but does not have any special checks for correctness +and only accepts a full class name. It also modifies the L to the +controller after constructing it. Passing a false value will result in +reverting the current context back to the app object. + +It's optimized for speed and only used internally, so it's not recommended to +use it unless you extend Kelp router itself. =head2 clear -Clears context in anticipation of the next request. +Clears context in anticipation of the next request. Called automatically at the +start of every request. diff --git a/lib/Kelp/Manual/Controllers.pod b/lib/Kelp/Manual/Controllers.pod index 738f1e1..091add1 100644 --- a/lib/Kelp/Manual/Controllers.pod +++ b/lib/Kelp/Manual/Controllers.pod @@ -16,14 +16,15 @@ class. Controllers lets you separate some of the route handling logic to other classes and have your subs take the object of the correct class as the first argument. -In Kelp, there is no special base class for controllers - all controllers must -be subclasses of L. +In Kelp, there is no special base class for controllers by default - all +controllers must be subclasses of L, unless you want to develop your own +base controller - see L. =head2 Reblessing details Reblessing will happen after request is matched to a route. Route handler has to be specified as class and method string, and class must be a subclass of class -configured for L. L must albo be +configured for L. L must also be enabled for that to occur. The default value of C field is the application class, so your @@ -206,8 +207,8 @@ default C, which is the class name of the context: =head1 CAVEATS -There are some controller gotchas which come from a fact that they are not -constructed like a regular object: +There are some controller gotchas which come from a fact that they are not by +default constructed like a regular object: =head2 Main application object is shallow-cloned before rebless @@ -233,12 +234,12 @@ long as you don't instantiate your controllers before app building is finished. Controllers are never actually constructed, but instead the main app object is cloned and reblessed into the correct class. Don't expect your override of -C or C to work. +C or C to ever be called. No automatic controller initialization +happens in Kelp. -No automatic controller initialization happens in Kelp. If you'd like to access -a controller in other context than route handling - for example in C -method, allowing you to move route definitions to the controller - you may use -C tracking object: +If you'd like to access a controller in other context than route handling - for +example in C method, allowing you to move route definitions to the +controller - you may use C tracking object: # in MyApp.pm sub build { diff --git a/lib/Kelp/Manual/Cookbook.pod b/lib/Kelp/Manual/Cookbook.pod index 198e830..23b480f 100644 --- a/lib/Kelp/Manual/Cookbook.pod +++ b/lib/Kelp/Manual/Cookbook.pod @@ -89,18 +89,9 @@ A slightly shorter version with state variables and no ping: # Use $self->dbh from here on ... - sub some_route { - my $self = shift; - - $self->dbh->selectrow_array(q[ - SELECT * FROM users - WHERE clue > 0 - ]); - } - Same methods can be used for accessing the schema of L. -=head2 Custom 404 and 500 error pages +=head2 Custom error pages =head3 Error templates @@ -112,49 +103,14 @@ C<< $self->res->render_error >>. =head3 Within the route -You can set the response headers and content within the route: +For one-off rendering of errors, you can alternatively set the response headers +and content within the route: sub some_route { my $self = shift; $self->res->set_code(404)->template('my_404_template'); } -=head3 By overriding the Kelp::Response class - -To make custom 500, 404 and other error pages, you will have to subclass the -L module and override the I and I subroutines. -Let's say your app's name is Foo and its class is in I. Now create a -file I: - - package Foo::Response; - use Kelp::Base 'Kelp::Response'; - - sub render_404 { - my $self = shift; - $self->template('my_custom_404'); - } - - sub render_500 { - my $self = shift; - $self->template('my_custom_500'); - } - -Then, in I, you have to tell Kelp to use your custom response class -like this: - - sub response { - my $self = shift; - return Foo::Response->new( app => $self ); - } - -Don't forget you need to create I and -I. You can add other error rendering subroutines too, for -example: - - sub render_401 { - # Render your custom 401 error here - } - =head2 Altering the behavior of a Kelp class method The easiest solution would be to use L module available on CPAN: @@ -228,9 +184,14 @@ use L. (REMOTE_ADDR is not set at all when using the proxy via filesocket). -=head2 Changing the default access logging +=head2 Changing the default logging + +Default log format can be modified by configuring the C module. See +L and L. +Alternatively, L can be configured with its own callback to +format the message to be logged. -Access logs reported by Kelp through C can be modified or disabled by +Access logs reported by Kelp through C can be modified or disabled by writing your own customized L method (not calling the parent version).