NAME

Catalyst::Controller::Atompub::Collection - A Catalyst controller for the Atom Collection Resources

COMPATIBILITY ISSUES

An accessor for edited was obsoleted since v0.1.0.

package MyAtom::Controller::MyCollection;
use base 'Catalyst::Controller::Atompub::Collection';

sub create_entry :Atompub(create) {
    # ...

    # Old accessor (can be still used, but will be removed)
    $self->entry_resource->edited;

    # New accessor
    $self->edited;

    # ...
}

SYNOPSIS

package MyAtom::Controller::MyCollection;
use base 'Catalyst::Controller::Atompub::Collection';

# List resources in a Feed Document, which must be implemented in
# the mehtod with "Atompub(list)" attribute
sub get_feed :Atompub(list) {
    my ( $self, $c ) = @_;

    # Skeleton of the Feed (XML::Atom::Feed) was prepared by 
    # C::C::Atompub
    my $feed = $self->collection_resource->body;

    # Retrieve Entries sorted in descending order
    my $rs = $c->model('DBIC::Entries')
               ->search( {}, { order_by => 'edited desc' } );

    # Add Entries to the Feed
    while ( my $entry_resource = $rs->next ) {
        my $entry = XML::Atom::Entry->new( \$entry_resource->xml );
        $feed->add_entry( $entry );
    }

    # Return true on success
    return 1;
}

# Create new Entry in the method with "Atompub(create)" attribute
sub create_entry :Atompub(create) {
    my ( $self, $c ) = @_;

    # URI of the new Entry, which was determined by C::C::Atompub
    my $uri = $self->entry_resource->uri;

    # app:edited element, which was assigned by C::C::Atompub,
    # is coverted into ISO 8601 format like '2007-01-01 00:00:00'
    my $edited = $self->edited->iso;

    # POSTed Entry (XML::Atom::Entry)
    my $entry = $self->entry_resource->body;

    # Create new Entry
    $c->model('DBIC::Entries')->create( {
        uri    => $uri,
        edited => $edited,
        xml    => $entry->as_xml,
    } );

    # Return true on success
    return 1;
}

# Search the requested Entry in the method with "Atompub(read)"
# attribute
sub get_entry :Atompub(read) {
    my ( $self, $c ) = @_;

    my $uri = $c->req->uri;

    # Retrieve the Entry
    my $rs = $c->model('DBIC::Entries')->find( { uri => $uri } );

    # Set the Entry
    my $entry = XML::Atom::Entry->new( \$rs->xml );
    $self->entry_resource->body( $entry );

    # Return true on success
    return 1;
}

# Update the requested Entry in the method with "Atompub(update)"
# attribute
sub update_entry :Atompub(update) {
    my ( $self, $c ) = @_;

    my $uri = $c->req->uri;

    # app:edited element, which was assigned by C::C::Atompub,
    # is coverted into ISO 8601 format like '2007-01-01 00:00:00'
    my $edited = $self->edited->iso;

    # PUTted Entry (XML::Atom::Entry)
    my $entry = $self->entry_resource->body;

    # Update the Entry
    $c->model('DBIC::Entries')->find( { uri => $uri } )
                              ->update( {
                                  uri => $uri,
                                  edited => $edited,
                                  xml => $entry->as_xml,
                              } );

    # Return true on success
    return 1;
}

# Delete the requested Entry in the method with "Atompub(delete)"
# attribute
sub delete_entry :Atompub(delete) {
    my ( $self, $c ) = @_;

    my $uri = $c->req->uri;

    # Delete the Entry
    $c->model('DBIC::Entries')->find( { uri => $uri } )->delete;

    # Return true on success
    return 1;
}
    
# Access to http://localhost:3000/mycollection and get Feed Document

DESCRIPTION

Catalyst::Controller::Atompub::Collection provides the following features:

Pre-processing requests

Catalyst::Controller::Atompub::Collection pre-processes the HTTP requests. All you have to do is just writing CRUD operations in the subroutines with Atompub attribute.
Media Resource support

Media Resources (binary data) as well as Entry Resources are supported. A Media Link Entry, which has an atom:link element to the newly created Media Resource, is given by Catalyst::Controller::Atompub::Collection.
Media type check

Catalyst::Controller::Atompub::Collection checks a media type of the POSTed/PUTted resource based on collection configuration.
Category check

Catalyst::Controller::Atompub::Collection checks atom:category elements in the POSTed/PUTted Entry Document based on collection configuration.
Cache controll and versioning

Cache controll and versioning are enabled just by overriding find_version method, which returns ETag and/or Last-Modified header.
Naming resources by Slug header

Resource URIs are determined based on Slug header if exists. If the Slug header is "Entry 1", the resource URI will be like:
```
http://localhost:3000/mycollection/entry_1.atom
```
The default naming rules can be changed by overriding make_edit_uri method.

SUBCLASSING

One or more subclasses are required in your Atompub server implementation. In the subclasses, methods with the following attributes must be defined.

sub xxx :Atompub(list)

Lists resources in a Feed Document.

This method is expected to add Entries and other elements to a skeleton of the Feed. The following accessors can be used.

- $controller->collection_resource->uri: URI of Collection
- $controller->collection_resource->body: Skeleton of Feed (XML::Atom::Feed)