/ 
XML-OPDS-0.06
River stage zero No dependents
/ XML::OPDS

NAME

XML::OPDS - OPDS (Open Publication Distribution System) feed creation

VERSION

Version 0.06

DESCRIPTION

This module facilitates the creation of OPDS feeds.

The specifications can be found at http://opds-spec.org/ while the validator is at http://opds-validator.appspot.com/.

The idea is that it should be enough to pass the navigation links and the title entries with some data, and have the feed back.

The OPDS feeds are basically Atom feeds, hence this module uses XML::Atom under the hood.

Some features are not supported yet, but patches are welcome. Also keep in mind that the applications which are supposed to talk to your server have a level of support which varies from decent to "keep crashing".

This is still very much a work in progress, but it's already generating valid and usable catalogs.

SYNOPSIS

use XML::OPDS;
my $feed = XML::OPDS->new(prefix => 'http://amusewiki.org');
# add two links, self and start are mandatory.
$feed->add_to_navigations(
                          rel => 'self',
                          title => 'Root',
                          href => '/',
                         );
$feed->add_to_navigations(
                          rel => 'start',
                          title => 'Root',
                          href => '/',
                         );
# add a navigation for the title list, marking as leaf, where the
# download links can be retrieved.
$feed->add_to_navigations(
                          title => 'Titles',
                          description => 'texts sorted by title',
                          href => '/titles',
                          acquisition => 1,
                         );
# and render
print $feed->render;
# you can reuse the object for leaf feeds (i.e. the acquistion
# feeds), pushing another self navigation, which will replace the
# previous one.
$feed->add_to_navigations(
                          rel => 'self',
                          title => 'Titles',
                          description => 'texts sorted by title',
                          href => '/titles',

                         );
# or, implicitely setting the self rel and cleaning the navigation
# stash, keeping the meta
$feed->add_to_navigations_new_level(
                                    title => 'Titles',
                                    acquisition => 1,
                                    href => '/titles',
                                   );
$feed->add_to_acquisitions(
                           href => '/my/title',
                           title => 'My title',
                           files => [ '/my/title.epub' ],
                          );
# and here we have an acquisition feed, because of the presence of
# the acquisition.
print $feed->render;

ENCODING

Even if the module wants characters as input (decoded strings, not bytes), the output XML is an UTF-8 encoded string.

SETTERS/ACCESSORS

Arrayref of XML::OPDS::Navigation objects. An object with a rel self (the feed itself) and one with the rel start (the root feed) are mandatory. If not present, the module will crash while rendering the feed.

acquisitions

Arrayref of XML::OPDS::Acquisition objects. If one or more objects are present, the feed will become an acquistion feed.

author

The producer of the feed. Defaults to this class name and version.

author_uri

The uri of the author. Defaults to http://amusewiki.org (which is the home of this class).

prefix

Default to the empty string. On instances of this class, by itself has no effect. However, when calling add_to_acquisitions and add_to_navigations, it will be passed to the constructors of those objects.

This is usually the hostname of the OPDS server. So you need just to pass, e.g. 'http://amusewiki.org' and have all the links prefixed by that (no slash mangling or adding is performed). If you are going to pass the full urls, leave it at the default.

updated

Default to current timestamp. When calling create_navigation or create_acquistion, use this timestamp as default.

The feed logo. If prefix is set, prepend it.

icon

The feed icon. If prefix is set, prepend it.

METHODS

render

Return the generated xml.

atom

Return the XML::Atom::Feed object.

create_navigation(%args)

Create a XML::OPDS::Navigation object inheriting the prefix.

create_acquisition(%args)

Create a XML::OPDS::Acquisition object inheriting the prefix.

add_to_navigations(%args)

Call create_navigation and add it to the navigations stack.

add_to_navigations_new_level(%args)

Like add_to_navigations, but it's meant to be used for rel:self elements.

The rel:self attribute is injected in the arguments which are passed to create_navigation.

If a navigation with the attribute rel set to self was already present in the stack, the new one will become the new self, while the old one will become an up rel.

Also, this will remove any existing navigation with the rel attribute set to subsection, given that you are creating a new level.

This is designed to play well with chained actions (so you can reuse the object, stack selfs, and the result will be correct).

add_to_acquisitions(%args)

Call create_acquisition and add it to the acquisition stack.

INTERNAL METHODS

Return a list of XML::OPDS::Navigation objects excluding unique relationships like self, start, up, previous, next, first, last.

Return an hashref, where the keys are the rel attributes of the navigation objects. The value is an object if the navigation is meant to be unique, or an arrayref of objects if not so.

is_acquisition

Return true if there are acquisition objects stacked.

OPENSEARCH RESULTS

The following attributes can be set if you are building an Atom response for OpenSearch. See XML::OPDS::OpenSearch::Query for a concrete example.

search_result_pager

A Data::Page object with the specification of the pages.

search_result_terms

A string with the query for which you are serving the results.

search_result_queries

Additional Query elements, should be an arrayref of XML::OPDS::OpenSearch::Query objects.

AUTHOR

Marco Pessotto, <melmothx at gmail.com>

BUGS

Please report any bugs or feature requests to bug-xml-opds at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-OPDS. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc XML::OPDS

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2016 Marco Pessotto.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.