NAME

CatalystX::Action::Negotiate - ActionRole for content negotiation

VERSION

Version 0.01

SYNOPSIS

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
}

DESCRIPTION

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.

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.

Interacting with the action in a handler goes as follows:

1. 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.

2. The action runs the calling handler, offering it an opportunity to manipulate the variant list or intercede in the response.

3. 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.

4. The action performs a trailing-slash check to match the request-URI to the internal representation, redirecting if necessary with a code 301.

5. An If-Modified-Since check is performed, which will return 304 if the client already has the latest version of the document.

6. If the action has not terminated the response by now, it sets the response body to the variant and the status to 200.

   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:

   1. 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.

   2. Path::Class::File objects get special treatment, as they are what the initial static variant list is made out of.

   3. Append an additional integer to the end of a variant's record to supply an artificial Last-Modified value as a UNIX time stamp.

   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.

SEE ALSO

• Catalyst::Action

• HTTP::Negotiate

• Role::MimeInfo

AUTHOR

Dorian Taylor, <dorian at cpan.org>

BUGS

Please report bugs on GitHub.

SUPPORT

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

LICENSE AND COPYRIGHT

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.