Object::eBay::Item - Represents an item listed on eBay

Object-eBay documentation Contained in the Object-eBay distribution.

Index

Code Index:

NAME

Top

Object::eBay::Item - Represents an item listed on eBay

SYNOPSIS

Top

    # assuming that Object::eBay has already been initialized
    use Object::eBay::Item;
    my $item = Object::eBay::Item->new({ item_id => 12345678 });

    print "The item is titled '", $item->title(), "'\n";

DESCRIPTION

Top

An Object::eBay::Item object represents an item that has been listed for sale on eBay.

METHODS

Top

new

A single 'item_id' argument is required. The value of the argument should be the eBay item ID of the item you want to represent.

attributes

Returns an Object::eBay::Attributes object representing all the attributes about this item. If you plan to use this method, you must specify 'attribute_set_array' (sorry) in the needs_methods list when creating the object (see new in Object::eBay). If you don't specify needs_methods correctly, this method will return incorrect results.

buy_it_now_price

Returns an Object::eBay::Currency object indicating the "Buy It Now" price for this item. If the item has no Buy It Now price, a price of "0" is returned. Although this may not be optimal behavior, it adhere's to eBay's usage.

country

Returns a code indicating the item's country. This method may need to be deprecated because the docs on eBay are contradictory. Use it with caution.

description

Returns the HTML text of the item's description. If you plan to use this method, please specify 'description' in the needs_methods list when creating the object (see new in Object::eBay). If you don't specify needs_methods correctly, this method will return incorrect results.

is_ended

Returns an Object::eBay::Boolean true value if the eBay auction for this item has ended. Otherwise, it returns a false object.

item_id

Returns the eBay item ID for this auction. This is the same as the "item_id" argument to new. This method also provides the value when an Item object is used in string context.

listing_details

Returns a Object::eBay::ListingDetails object.

pictures

Returns a list of URLs for the pictures associated with this item. The eBay API defines multiple ways in which images can be associated with a particular item. This method searches each of those ways and returns a list of all the image URLs that it found. If no images are found, an empty list is returned. At this time, the URLs are simple scalars and not objects, however that may change. If the return value changes, the string context will still represent the URL as it does now.

quantity

Returns the quantity for sale with this item.

seller

Returns a Object::eBay::User object representing the item's seller. Not all methods of Object::eBay::User are necessarily available.

selling_status

Returns a Object::eBay::SellingStatus object

title

Returns the title of the item.

watch_count

Returns the number of watches that have been place on this item via "My eBay" If you plan to use this method on an Object::eBay::Item object, please specify 'watch_count' in the needs_methods list when creating the object (see new). If you don't specify needs_methods correctly, this method will not be available.

DIAGNOSTICS

Top

None

CONFIGURATION AND ENVIRONMENT

Top

Object::eBay::Item requires no configuration files or environment variables.

DEPENDENCIES

Top

* Class::Std
* Object::eBay

INCOMPATIBILITIES

Top

None known.

BUGS AND LIMITATIONS

Top

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

SUPPORT

Top

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

    perldoc Object::eBay

You can also look for information at:

* AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/Object-eBay

* CPAN Ratings

http://cpanratings.perl.org/d/Object-eBay

* RT: CPAN's request tracker

http://rt.cpan.org/NoAuth/Bugs.html?Dist=Object-eBay

* Search CPAN

http://search.cpan.org/dist/Object-eBay

ACKNOWLEDGEMENTS

Top

AUTHOR

Top

Michael Hendricks <michael@ndrix.org>

LICENSE AND COPYRIGHT

Top

Copyright (c) 2006 Michael Hendricks (<michael@ndrix.org>). All rights reserved.

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

Object-eBay documentation Contained in the Object-eBay distribution. 
package Object::eBay::Item;
our $VERSION = '0.4.0';

use Class::Std; {
    use warnings;
    use strict;
    use base qw( Object::eBay );
    use overload '""' => 'item_id', fallback => 1;
    use Object::eBay::Boolean;
    use Object::eBay::Attributes;

    sub api_call       { "GetItem" };
    sub response_field { "Item"    };

    __PACKAGE__->simple_attributes(qw{
        Country
        Title
        Quantity
    });

    __PACKAGE__->complex_attributes({
        AttributeSetArray => {
            class       => 'Attributes',
            DetailLevel => 'ItemReturnAttributes',
        },
        BuyItNowPrice => {
            class => 'Currency',
        },
        Seller => {
            class => 'User',
        },
        SellingStatus => {
            class => 'SellingStatus',
        },
        ListingDetails => {
            class => 'ListingDetails',
        },
        Description => {
            DetailLevel => 'ItemReturnDescription',
        },
        WatchCount => {
            IncludeWatchCount => 'true',
        },
    });

    sub item_id  { shift->api_inputs->{ItemID} }

    sub attributes {
        my $attributes = eval { shift->attribute_set_array };
        return $attributes if $attributes;

        # some auctions have no attributes at all
        # in this case, we want an empty Attributes object
        return Object::eBay::Attributes->new({ object_details => 'none' });
    }

    sub is_ended {
        my ($self) = @_;
        my $status = $self->selling_status->listing_status;
        die "eBay item #$self has no listing status\n" if not defined $status;

        my $true = Object::eBay::Boolean->true;
        my $false = Object::eBay::Boolean->false;

        return $false if $status eq 'Active';
        return $true  if $status eq 'Ended';
        return $true  if $status eq 'Completed';
        die "eBay item #$self has an unknown listing status: $status\n";
    }

    #########################################################################
    # Usage     : my @images = $item->pictures()
    # Purpose   : Combine various sources of pictures into one method
    # Returns   : a list of image URLs
    # Arguments : none
    # Throws    : no exceptions
    # Comments  : none
    # See Also  : n/a
    sub pictures {
        my ($self) = @_;

        # TODO this should probably be implemented in terms of other
        # methods instead of manually searching the details hash
        # but I haven't implement those other methods yet.

        my @places = (
            [qw( PictureDetails      GalleryURL    )],
            [qw( PictureDetails      PictureURL    )],
            [qw( SiteHostedPicture   PictureURL    )],  # deprecated
            [qw( VendorHostedPicture SelfHostedURL )],  # deprecated
        );
        
        my $details = $self->get_details();
        return if !$details;

        my @image_urls;
        PLACE:
        for my $place (@places) {
            my ($major, $minor) = @$place;
            next PLACE if !exists $details->{$major};
            next PLACE if !exists $details->{$major}{$minor};

            my $url = $details->{$major}{$minor};
            next PLACE if !defined $url;
            push @image_urls, ( ref $url eq 'ARRAY' ? @$url : $url );
        }

        return @image_urls;
    }
}

1;

__END__