NAME

Plack::App::SeeAlso - SeeAlso Server as PSGI application

VERSION

version 0.10

SYNOPSIS

    # create SeeAlso server with code reference
    use Plack::App::SeeAlso;
    my $app = Plack::App::SeeAlso->new( 
        Query => sub {
            my $id = shift;
            return unless $id =~ /:/; # return undef for empty response
            
            # ... create and return response            
            return [ $id, [ "label" ], 
                          [ "hello" ], 
                          [ "http://example.org" ] ];

            # ... alternatively create with 'push_seealso'
            push_seealso [$id], "label", "hello", "http://example.org";
        }, ShortName => 'My Server' 
    );

    # create SeeAlso server as subclass
    use parent 'Plack::App::SeeAlso';

    our $ShortName   = 'My Server';
    our $Contact     = 'admin@example.org';
    our $Description = '...';

    sub query {
        my ($self, $id) = @_;
        # ...
    }

DESCRIPTION

This module implements the a SeeAlso Linkserver Protocol server as PSGI application. SeeAlso is basically based on two HTTP protocols, unAPI and OpenSearch (Open Search Suggestions and Open Search Description documents).

You can simply implement a SeeAlso server by creating an instance of Plack::App::SeeAlso or by deriving this class and implementing

This module contains a SeeAlso client in form of three files (seealso.js, seealso.xsl, seealso.css). This client is served if no format-parameter was given, so you get a nice, human readable interface.

METHODS

new ( [ %properties ] )

Creates a new SeeAlso server. The following optional properties are supported, most of them to be used as OpenSearch description elements:

Query

A code reference to be used as query method.

ShortName

Short name of the server (truncated to 16 characters).

LongName

Long name of the server (truncated to 48 characters).

Description

Verbal description of the server (truncated to 1024 characters).

Contact

An email address at which the maintainer of the server can be reached.

Developer

Human-readable name or identifier of the creator or maintainer of the server.

Tags

A set of words that are used as keywords to identify and categorize the server. Tags must be a single word and are delimited by the space character (truncated to 256 characters).

Attribution

A list of all sources or entities that should be credited for the content contained in the search feed (truncated to 256 characters).

Source

Verbal description of the source of the server (Dublin Core element dc:source).

DateModified

Timestamp of last modification of the server (qualified Dublin Core element Date.Modified).

Examples

A list of hash reference with id examples and optional response data, such as the following structure:

    [ 
      { id => 'foo' }, 
      { id => 'bar', 
        response => [ 'bar', ['label'],['description'],['uri'] ] }
    ]

Stylesheet

By default, an client interface is returned at /seealso.xsl, /seealso.js, and /seealso.css. A link to the interface is added if no format parameter was given. You can disable this interface by setting the Stylesheet option to undef or you set it to some URL of another XSLT file.

Formats

A hash reference with additional formats, to be used with Plack::App::unAPI.

The OpenSearch description element Url is set automatically. The elements SyndicationRight, AdultContent, Language, InputEncoding, and OutputEncoding are not supported.

query ( $identifier )

If you subclass this module, you are expected to implement a query method. The method receives a defined identifier (set to the empty string by default) as an argument and is expected to return either an Open Search Suggestions response or undef. An Open Search Suggestions response is an array reference with two to three elements:

• The first element is the identifier, possibly normalized.

• The second element is an array reference with labels as strings.

• The third element is an array reference with descriptions as strings.

• The fourth element is an arary reference with URIs as strings.

push_seealso ( $response, $label, $description, $uri )

This utility method/function is exported by default. You can use it to append a single response item to a response array reference:

    $resp = [$id,[],[],[]];
    push_seealso $resp, $label, $descr, $uri;
    # $resp is now [$id,[$label],[$descr],[$uri]];

NOTES

This module sets the default MIME type for .xsl files to text/xsl because browser will more likely complain otherwise. This setting is done with Plack::MIME and it may also affect other applications.

SEE ALSO

This module is basically a refactored clean-up of SeeAlso::Server. The unAPI handling is done by module Plack::App::unAPI. An introductionary article about unAPI can be found at http://www.ariadne.ac.uk/issue57/voss/.

AUTHOR

Jakob Voss

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Jakob Voss.

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