/ 
Leyland-1.000001
River stage zero No dependents
/ Leyland::Manual::Extending

NAME

Leyland::Manual::Extending - How to extend Leyland

VERSION

version 1.000001

EXTENDING THE CONTEXT CLASS

The context class (Leyland::Context) constitutes the most of Leyland's API provided for your applications. It follows a request during its entire lifetime. It is very likely that you'd like that class to have attributes and methods which are specific to your application, such as an attribute that holds a database connection object for example.

If so needed, Leyland gives you the ability to easily extend the base context class. Since it is Moo based, you can create a class that extends it, and tell Leyland to use it as the application's context class.

For example, our application can have the following class:

package MyApp::Context;

use Moo;
use namespace::clean;

extends 'Leyland::Context';

has 'db' => (is => 'ro', writer => '_set_db');

around 'loc' => sub {
	my ($orig, $self) = (shift, shift);

	# change the behavior of the loc() method
};

1;

And we can tell Leyland to use it as the context class when initiating an instance of our class in app.psgi:

my $myapp = MyApp->new(context_class => 'MyApp::Context');

But how do you populate the db attribute we see in the above example? Most likely with the root controller's auto() method:

# MyApp/Controller/Root.pm
sub auto {
	my ($self, $c) = @_;

	$c->_set_db(SomeDatabaseClass->new);
}

Leyland also allows classes that extend Leyland::Context to define a method called finalize. This method is called right before a response is sent to the client (but only before successful responses, not exceptions), after serialization (if performed). The method receives a reference to the returned output (which will be scalar). The reason a reference is passed to the method is to allow it to modify it. A simple example would be:

# in MyApp/Context.pm
sub finalize {
	my ($c, $ret) = @_;

	$$ret =~ s/John/Michael/g;
}

Of course, be careful if you decide to modify any of Leyland::Context's methods so as not to break its behavior.

EXTENDING LEYLAND

If you find that Leyland lacks support for your preferred CPAN modules, such as template engines, you are more than welcome to create these classes by yourself. View classes are expected to consume Leyland::View, which describes how view classes should be created. Look at Leyland::View::Tenjin for an example.

If you want to go even further, since Leyland is entirely Moo(se) based, and if you're crazy enough, you can use Moo(se) tricks and modifications to make Leyland behave the way you want it, and maybe even create your own application framework on top of Leyland.

HELPING WITH DEVELOPMENT

You are more than welcome to help with the development of Leyland, even by simply submitting suggestions and bug reports. Refer to "BUGS" in Leyland and "SUPPORT" in Leyland for more information on submitting bug reports. Leyland development is version controlled via GitHub, at http://github.com/ido50/Leyland. If you're also using GitHub, feel free to fork Leyland, send me pull requests, etc.

WHAT'S NEXT?

Refer to Leyland::Manual::FAQ for frequently asked questions and their answers, or return to the table of contents.

AUTHOR

Ido Perlmuter, <ido at ido50.net>

BUGS

Please report any bugs or feature requests to bug-Leyland at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Leyland. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Leyland::Manual::Extending

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010-2014 Ido Perlmuter.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.