| Web::Machine::Resource(3pm) | User Contributed Perl Documentation | Web::Machine::Resource(3pm) |
Web::Machine::Resource - A base resource class
version 0.17
package HelloWorld::Resource;
use strict;
use warnings;
use parent 'Web::Machine::Resource';
sub content_types_provided { [{ 'text/html' => 'to_html' }] }
sub to_html {
q{<html>
<head>
<title>Hello World Resource</title>
</head>
<body>
<h1>Hello World</h1>
</body>
</html>}
}
This is the core representation of the web resource in Web::Machine. It is this object which is interrogated through the state machine. It is important not to think of this as an instance of a single object, but as a web representation of a resource: there is a big difference.
For now I am keeping the documentation short, but much more needs to be written here. Below you will find a description of each method this object provides and what is expected of it. Your resource classes should extend the base Web::Machine::Resource class, overriding its methods as necessary. Sane defaults are provided for most methods, but you will want to create a "content_types_provided" method, as without this your resource will not be able to return any useful content.
The documentation was lovingly stolen from the ruby port of webmachine.
Keep in mind that the methods may be called more than once per request, so your implementations should be idempotent.
If your resource is instantiated via Web::Machine then the contents of its "resource_args" parameter will be appended to the Web::Machine::Resource constructor arguments and made available to "init":
use strict;
use warnings;
use Web::Machine;
{
package HelloWorld::Resource;
use strict;
use warnings;
use JSON::XS qw[ encode_json ];
use parent 'Web::Machine::Resource';
sub init {
my $self = shift;
my $args = shift;
# Plack::Request
# my $request = $args->{request};
# Plack::Response
# my $response = $args->{response};
$self->{json}
= exists $args->{json}
? $args->{json}
: {};
}
sub content_types_provided { [ { 'application/json' => 'to_json' } ] }
sub to_json {
my $self = shift;
encode_json( $self->{json} );
}
}
Web::Machine->new(
resource => 'HelloWorld::Resource',
resource_args => [
json => {
message => 'Hello World!',
},
],
)->to_app;
Returning a false value will result in a '404 Not Found' response.
Defaults to true.
Returning a false value will result in a '503 Service Not Available' response.
Defaults to true.
If the resource is only temporarily not available, add a 'Retry-After' response header in the body of the method.
Parameter $authorization_header is the contents of the 'Authorization' header sent by the client, if present.
Returning anything other than 1 will result in a '401 Unauthorized' response. If a string is returned, it will be used as the value in the 'WWW-Authenticate' response header, which can also be set manually.
Defaults to true.
Returning a true value will result in a '403 Forbidden' response.
Defaults to false.
Defaults to false.
Defaults to false.
Defaults to false.
The value of $content_type is derived from the Plack::Request object and will therefore be an instance of the HTTP::Headers::ActionPack::MediaType class.
Defaults to true.
If the request includes any invalid Content-* headers, this should return false, which will result in a '501 Not Implemented' response.
Defaults to true.
If the entity length on PUT or POST is invalid, this should return false, which will result in a '413 Request Entity Too Large' response.
Defaults to true.
Defaults to {}.
Defaults to "['GET','HEAD']".
Default includes all standard HTTP methods, "['GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'TRACE', 'CONNECT', 'OPTIONS']".
Defaults to false.
Defaults to true.
Default is false.
Default is false.
Default is nil, which uses the URI of the request as the base.
For example, if a client request includes an 'Accept' header with a value that does not appear as a first element in any of the return pairs, then a '406 Not Acceptable' will be sent.
The order of HASH ref pairs in the ARRAY is important. If no specific content type is requested (the client does not send an "Accept" header) then the first content type in the ARRAY will be used as the default.
Default is an empty ARRAY ref.
The return value from this method must be an ARRAY ref. Each member of that array can be either a string or a HASH ref pair value. If the member is a string, it must be a valid character set name for the Encode module. Web::Machine will call "encode()" on the body using this character set if you set a body.
sub charsets_provided {
return [ qw( UTF-8 ISO-8859-1 shiftjis ) ];
}
If you return a HASHREF pair, the key must be a character set name and the value must be a CODE ref. This CODE ref will be called as a method on the resource object. It will receive a single parameter, a string to be encoded. It is expected to return a scalar containing bytes, not characters. This will be used to encode the body you provide.
sub charsets_provided {
return [
{
'UTF-8' => sub {
my $self = shift;
my $string = shift;
return make_some_bytes($string),;
},
},
{
'ISO-8859-1' => sub {
my $self = shift;
my $string = shift;
return strip_non_ascii($string),;
},
},
];
}
The character set name will be appended to the Content-Type header returned the client.
If a client specifies the same preference for two or more character sets that your resource provides, then Web::Machine chooses the first character set in the returned ARRAY ref.
CAVEAT: Note that currently "Web::Machine" does not support the use of encodings when the body is returned as a CODE ref. This is a bug to be remedied in the future.
Default is an empty list.
This works just like the "charsets_provided()" method, except that you can only return a single value.
CAVEAT: Note that currently "Web::Machine" does not support the use of encodings when the body is returned as a CODE ref. This is a bug to be remedied in the future.
Default includes only the 'identity' encoding.
Default is [].
Default is false.
Default is false.
Default is false.
Default is to return false.
Default is to return false.
Default is undef.
Default is nil.
Default is undef.
The return value is ignored, so any effect of this method must be by modifying the response.
bugs may be submitted through <https://github.com/houseabsolute/webmachine-perl/issues>.
This software is copyright (c) 2016 by Infinity Interactive, Inc.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
| 2017-01-26 | perl v5.24.1 |