CatalystX::Action::Negotiate - ActionRole for content negotiation
Version 0.02
sub default :Path :Does('+CatalystX::Action::Negotiate') { my ($self, $c) = @_; # obtain variants (if you care) my @variants = @{$c->stash->{variants}}; # maybe manipulate them? i dunno # set them back, or set entirely new ones $c->stash->{variants} = \@variants; # action role negotiates variants and returns the winner }
This module serves content-negotiated static content from the document root. It also affords mixing dynamic variants in with static variants, the list of which is passed directly into the "choose" in HTTP::Negotiate function. The winning variant is chosen from the various Accept-* request headers.
Accept-*
As with Apache and other Web servers, dimensions for static variants are derived from file extensions. Currently the only supported dimension is MIME content type.
There is a slight difference in the behaviour between this module and Apache: whereas there is one or more files of the form foo.* alongside a directory called foo containing one or more files with the slug index, these will all be lumped into the set of variants. The customary trailing slash, however, will only be applied in the case that a foo/index.* file is chosen over a foo.* file. This is different from Apache in that the latter ignores foo.* files if there is also a directory present called foo. The purpose of this change is to provide an easy way to style URIs without the trailing slash while still providing for descendants along the same URI path.
foo.*
foo
index
foo/index.*
Interacting with the action in a handler goes as follows:
The action runs and first attempts to collect any eligible static variants found by concatenating the request-URI to the document root. It puts what it finds in $c->stash->{variants}. To indicate the indeterminate state of the response to the caller, the status is initially set to 404.
$c->stash->{variants}
The action runs the calling handler, offering it an opportunity to manipulate the variant list or intercede in the response.
If the handler has not changed the response code to a value below 400, the action proceeds to select a variant and set the appropriate headers.
The action performs a trailing-slash check to match the request-URI to the internal representation, redirecting if necessary with a code 301.
An If-Modified-Since check is performed, which will return 304 if the client already has the latest version of the document.
If-Modified-Since
If the action has not terminated the response by now, it sets the response body to the variant and the status to 200. If you need to, you can still manipulate it in a subsequent (e.g. end) handler.
end
The calling controller action is sandwiched between the variant-generating operation and the variant-selecting operation. It is placed as an ARRAY reference for your convenience in $c->stash->{variants}. This structure is exactly the same as that which is passed into HTTP::Negotiate, save for these exceptions:
ARRAY
Variants do not need to be a string identifier, but in fact can be anything that can be consumed by a view or middleware component, e.g., a file handle or any other kind of supported object.
Path::Class::File objects get special treatment, as they are what the initial static variant list is made out of.
Append an additional integer to the end of a variant's record to supply an artificial Last-Modified value as a UNIX time stamp.
Last-Modified
Otherwise, consult HTTP::Negotiate for how to construct the records. This modification enables you to mix static variants in with dynamic ones, or overwrite the list with purely dynamic variants.
Catalyst::Action
HTTP::Negotiate
Role::MimeInfo
Dorian Taylor, <dorian at cpan.org>
<dorian at cpan.org>
Please report bugs on GitHub.
You can find documentation for this module with the perldoc command.
perldoc CatalystX::Action::Negotiate
You can also look for information at:
MetaCPAN
http://metacpan.org/release/CatalystX-Action-Negotiate/
The source
https://github.com/doriantaylor/p5-catalystx-action-negotiate
Copyright 2019 Dorian Taylor.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
To install CatalystX::Action::Negotiate, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CatalystX::Action::Negotiate
CPAN shell
perl -MCPAN -e shell install CatalystX::Action::Negotiate
For more information on module installation, please visit the detailed CPAN module installation guide.