Jakob Voß > Plack-Middleware-Negotiate-0.05 > Plack::Middleware::Negotiate

Download:
Plack-Middleware-Negotiate-0.05.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.05   Source   Latest Release: Plack-Middleware-Negotiate-0.10

NAME ^

Plack::Middleware::Negotiate - Apply HTTP content negotiation as Plack middleware

VERSION ^

version 0.05

SYNOPSIS ^

    builder {
        enable 'Negotiate',
            formats => {
                xml  => { 
                    type    => 'application/xml',
                    charset => 'utf-8',
                },
                html => { type => 'text/html', language => 'en' },
                _    => { size => 0 }  # default values for all formats           
            },
            parameter => 'format', # e.g. http://example.org/foo?format=xml
            extension => 'strip';  # e.g. http://example.org/foo.xml
        $app; # neither html nor xml requested
    };

DESCRIPTION ^

Plack::Middleware::Negotiate applies HTTP content negotiation to a PSGI request. The PSGI environment key negotiate.format is set to the chosen format name. In addition to normal content negotiation one may enable explicit format selection with a path extension or query parameter. The middleware takes care for rewriting and restoring PATH_INFO if it is configured to detect and strip a format extension. The PSGI response is enriched with corresponding HTTP headers Content-Type and Content-Language unless these headers already exist.

If used as pure application, this middleware returns a HTTP status code 406 if no format could be negotiated.

METHODS ^

new ( formats => { ... } [ %argument ] )

Creates a new negotiation middleware with a given set of formats. The argument parameter can be added to support explicit format selection with a query parameter. The argument extension can be used to support explicit format selection with a virtual file extension. Use format => 'strip' to strip a known format name from the request path and format => 'keep' to keep it. Each format can be defined with type, quality (defaults to 1), encoding, charset, and language. The special format name _ (underscore) is reserved to define default values for all formats.

Formats can also be used to directly route the request to a PSGI application:

    my $app = Plack::Middleware::Negotiate->new(
        formats => {
            json => { 
                type => 'application/json',
                app  => $json_app,
            },
            html => {
                type => 'text/html',
                app  => $html_app,
            }
        }
    );

negotiate ( $env )

Chooses a format based on a PSGI request. The request is first checked for explicit format selection via parameter and extension (if configured) and then passed to HTTP::Negotiate. Returns the format name. May modify the PSGI request environment keys PATH_INFO and SCRIPT_NAME if format was selected by extension set to strip, and strips the format query parameter from QUERY_STRING if parameter is set to a known format.

about ( $format )

If the format was specified, this method returns a hash with quality, type, encoding, charset, and language. Missing values are set to the default.

variants ()

Returns a list of content variants to be used in HTTP::Negotiate. The return value is an array reference of array references, each with seven elements: format name, source quality, type, encoding, charset, language, and size. The size is always zero.

add_headers ( \@headers, $format )

Add apropriate HTTP response headers for a format unless the headers are already given.

METHODS ^

LOGGING AND DEBUGGUNG ^

Plack::Middleware::Negotiate uses Log::Contextual to emit a logging message during content negotiation on logging level <trace>. Just set:

    $ENV{PLACK_MIDDLEWARE_NEGOTIATE_TRACE} = 1;

LIMITATIONS ^

The Content-Encoding HTTP response header is not automatically set on a response and content negotiation based on size is not supported. Feel free to comment on whether and how this middleware should support both.

SEE ALSO ^

Content negotiation in this module is based on HTTP::Negotiate. See HTTP::Headers::ActionPack::ContentNegotiation for an alternative approach. This module has some overlap with Plack::Middleware::SetAccept.

AUTHOR ^

Jakob Voß <voss@gbv.de>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2012 by Jakob Voß.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: