NAME
Leyland::Context - The working environment of an HTTP request and Leyland response
VERSION
version 1.000001
SYNOPSIS
# every request automatically gets a Leyland::Context object, which
# is available in your routes and your views:
post '^/blog$' {
my $post = Blog->new(
subject => $c->params->{subject},
user => $c->user,
date => DateTime->now,
text => $c->params->{text}
);
return $c->template('blog.html', { post => $post });
}
# by the way, since Leyland is RESTful, your application can accept
# requests of any content type, making the above something like
# this:
post '^/blog$' accepts 'text/plain' {
my $post = Blog->new(
subject => $c->params->{subject},
user => $c->user,
date => DateTime->now,
text => $c->data
);
return $c->template('blog.html', { post => $post });
}DESCRIPTION
The Leyland context object is the heart and soul of your application. Or something. Anyway, it's an object that escorts an HTTP request to somewhere in your application through its entire lifetime, up to the point where an HTTP response is sent back to the client. This is quite similar to the Catalyst context object.
The context object holds a lot of information about the request, such as its content type, its method, the parameters/content provided with it, the routes it matched in your application, etc. Your controllers and views will mostly interact with this object, which apart from the information mentioned just now, provides you with useful methods to generate the final response, and perform other necessary operations such as logging.
The Leyland context object inherits from Plack::Request, so you can use all of its attributes and methods. But keep in mind that this class performs some modifications on these methods, all documented in the "PLACK MODIFICATIONS" section.
This document is for reference purposes only, please refer to Leyland::Manual for more information on using the context object.
EXTENDS
ATTRIBUTES
app
Holds the <Leyland> object of the application.
cwe
Holds the Plack environment in which the application is running. This is the PLACK_ENV environment variable. See the -E or --env switch in plackup for more information. Defaults to 'development'.
res
The Plack::Response object used to respond to the client.
routes
An array reference of all routes matched by the request (there can be more than one).
current_route
The index of the route to be invoked in the "routes" attribute above. By default this would be the first route (i.e. index 0), unless passes are performed.
froutes
An array reference of all routes matched by an internal forward.
current_froute
The index of the route to be forwarded to in the "froutes" attribute above. By default this would be the first route (i.e. index 0), unless passes are performed.
controller
The controller class of the current route.
wanted_mimes
An array reference of all media types the client accepts, ordered by the client's preference, as defined by the "Accept" HTTP header.
want
The media type the Leyland::Negotiator has decided to return to the client.
lang
The language to use when localizing responses, probably according to the client's wishes. Defaults to 'en' for English.
stash
A hash-ref of data meant to be available for the views/templates when rendering resources.
user
Something (anything really) that describes the user that initiated the request. This attribute will only be defined by the application, you are free to choose whatever scheme of authentication as you wish, this attribute is provided for your convenience. You will use the set_user() method to set the value of this attribute.
json
A JSON::Any object for usage by routes as they see fit.
xml
An XML::TreePP object for usage by routes as they see fit.
_pass_next
Holds a boolean value indicating whether the route has decided to pass the request to the next matching route. Not to be used directly.
_data
Holds the content of the HTTP request for POST and PUT requests after parsing. Not to be used directly.
OBJECT METHODS
Since this class extends Plack::Request, it inherits all its methods, so refer to Plack::Request for a full list. However, this module performs some modifications on certain Plack::Request methods, all of which are documented in the "PLACK MODIFICATIONS" section.
leyland
An alias for the "app" attribute.
has_routes()
Returns a true value if the request matched any routes.
has_froutes()
Returns a true value if the request has routes matched in an internal forward.
set_lang( $lang )
Sets the language to be used for localization.
has_user()
Returns a true value if the "user" argument has a value.
set_user( $user )
Sets the "user" argument with a new value. This value could be anything, a simple string/number, a hash-ref, an object, whatever your app uses.
clear_user()
Clears the value of the "user" argument, if any. Useful for logout actions.
params()
A shortcut for $c->parameters->as_hashref_mixed. Note that this is read-only, so changes you make to the hash-ref returned by this method are not stored. For example, if you run $c->params->{something} = 'whoa', subsequent calls to $c->params will not have the "something" key.
data( [ $dont_parse ] )
Returns the data of the request for POST and PUT requests. If the data is JSON or XML, this module will attempt to automatically convert it to a Perl data structure, which will be returned by this method (if conversion will fail, this method will return an empty hash-ref). Otherwise, the data will be returned as is. You can force this method to return the data as is even if it's JSON or XML by passing a true value to this method.
If the request had no content, an empty hash-ref will be returned. This is different than version 0.003 and down where it would have returned undef.
pass()
Causes Leyland to invoke the next matching route, if any, after this request has finished (meaning it does not pass immediately). Since you will most likely want to pass routes immediately, use return $self->pass in your routes to do so.
render( $tmpl_name, [ \%context, $use_layout ] )
template( $tmpl_name, [ \%context, $use_layout ] )
Renders the view/template named $tmpl_name using the first view class defined by the application. Anything in the $context hash-ref will be automatically available inside the template, which will be rendered inside whatever layout template is defined, unless $use_layout is provided and holds a false value (well, 0 really). The context object (i.e. $c) will automatically be embedded in the $context hash-ref under the name "c", as well as the application object (i.e. $c->app) under the name "l". Anything in the stash (i.e. $c->stash) will also be embedded in the context hash-ref, but keys in $context take precedence to the stash, so if the stash has the key 'name' and $context also has the key 'name', then the one from $context will be used.
Returns the rendered output. You will mostly use this at the end of your routes as the return value.
The two methods are the same, template is provided as an alias for render.
forward( $path, [ @args ] )
Immediately forwards the request (internally) to a different location defined by $path. Leyland will attempt to find routes that match the provided path (without performing HTTP negotiations for the request's method, content type, accepted media types, etc. like Leyland::Negotiator does). The first matching route will be invoked, with @args passed to it (if provided). The returned output (before serializing, if would have been performed had the route been invoked directly) is returned and the route from which the forward has been called continues. If you don't want it to continue, simple use return $c->forward('/somewhere').
The path should include the HTTP method of the route to forward to, by prefixing $path with the method name and a colon, like so: $c->forward('POST:/somewhere'). If a method is not provided (i.e. $c->forward('/somewhere')), Leyland will assume a GET method. Note that this differs from version 0.003 and down, where it would forward to the first matching route, regardless of the method. This is a safety measure so you do not accidentally forward to DELETE routes.
Note that if no routes are found, a 500 Internal Server Error will be thrown, not a 404 Not Found error, as this really is an internal server error.
loc( $msg, [ @args ] )
Uses Leyland::Localizer to localize the provided string to the language defined in the "lang" attribute, possibly performing some replacements with the values provided in @args. See Leyland::Manual::Localization for more info.
exception( \%err )
Throws a Leyland::Exception. $err must have a "code" key with the error's HTTP status code, and most likely an "error" key with a description of the error. See Leyland::Manual::Exceptions for more information.
uri_for( $path, [ \%query ] )
Returns a URI object with the full URI to the provided path. If a $query hash-ref is provided, it will be converted to a query string and used in the URI object.
finalize( \$ret )
This method is meant to be overridden by classes that extend this class, if used in your application. It is automatically called after the route has been invoked and it gets a reference to the output returned from the route (after serialization, if performed), even if this output is a scalar (like HTML text), in which case $ret will be a reference to a scalar.
You can use it to modify and manipulate the returned output if you wish.
The default finalize() method provided by this class does not do anything.
accepts( $mime )
Returns a true value if the client accepts the provided MIME type.
INTERNAL METHODS
The following methods are only to be used internally:
FOREIGNBUILDARGS( \%args )
BUILD()
PLACK MODIFICATIONS
The following modifications are performed on methods provided by Plack::Request, from which this class inherits.
content()
Returns the request content after UTF-8 decoding it (Plack::Request doesn't decode the content, this class does since Leyland is purely UTF-8).
session()
Returns the psgix.session hash-ref, or, if it doesn't exist, an empty hash-ref. This is different from Plack::Request, which won't return anything if there is no session hash-ref. If psgix.session really doesn't exist, however, then the returned hash-ref won't be very useful and data entered to it will only be alive for the lifetime of the request.
query_parameters()
Returns a Hash::MuliValue object of query string (GET) parameters, after UTF-8 decoding them (Plack::Request doesn't decode the query, this class does since Leyland is purely UTF-8).
body_parameters()
Returns a Hash::MultiValue object of posted parameters in the request body (POST/PUT), after UTF-8 decoding them (Plack::Request doesn't decode the body, this class does since Leyland is purely UTF-8).
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::ContextYou can also look for information at:
RT: CPAN's request tracker
AnnoCPAN: Annotated CPAN documentation
CPAN Ratings
Search CPAN
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.