NAME

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

VERSION

version 0.01

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;
};

DESCRIPTION

Plack::Middleware::Negotiate applies HTTP content negotiation, and sets the PSGI environment key negotiate.format to the negotiated format name. It further adds HTTP headers Content-Type and Content-Language unless they already exist in the PSGI response. In addition to normal content negotiation one may enable explicit format selection with a path extension or query parameter.

METHODS

negotiate ( $env )

Returns the negotiated format name for a given PSGI request. May return undef if no format was found. May modify the request if extension is set to strip.

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.

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.