NAME

WebService::GData::Feed - Base class wrapping json atom feed for google data API v2.

SYNOPSIS

    use WebService::GData::Feed;

    my $feed = new WebService::GData::Feed($jsonfeed);

    $feed->title;
    $feed->author;
    my @entries = $feed->entry();#send back WebService::GData::Feed::Entry or a service related Entry object 

DESCRIPTION

inherits from WebService::GData

This package wraps the result from a query using the json format of the Google Data API v2 (no other format is supported!). It gives you access to some of the data via wrapper methods and works as a factory to get access to the entries for each service. If you use a YouTube service, calling the entry() method will send you back YouTube::Feed::Entry's. If you use a Calendar service, calling the entry() method will send you back a Calendar::Feed::Entry. By default, it returns a WebService::GData::Feed::Entry which gives you only a read access to the data. Unless you implement a service, you should not instantiate this class directly.

CONSTRUCTOR

new

    Create a WebService::GData::Feed instance.

    Accept a json feed entry that has been perlified (from_json($json_string)) and an optional request object (WebService::GData::Base). The request object is passed along each entry classes but the Feed class itself does not use it.

    Parameters

    json_feed:Object - a json feed perlified
    request:Object - a request object WebService::GData::Base

    Returns

    WebService::GData::Feed

SET/GET METHODS

All the following methods work as both setter and getters.

title

    set/get the title of the feed.

    Parameters

    none - as a getter
    title:Scalar as a setter

    Returns

    none - as a setter
    title:Scalar as a getter

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed();
        
        $feed->title("my Title");
        
        $feed->title();#my Title

GET METHODS

All the following methods work as getters and do not accept parameters.

id

    Get the id of the feed.

    Parameters

    none - getter

    Returns

    id:Scalar

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        $feed->id();#"tag:youtube.com,2008:video"
       

updated

    Get the updated date of the feed.

    Parameters

    none - getter

    Returns

    updated:Scalar

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        $feed->updated();#"2010-09-20T13:49:20.028Z"
       

category

    Get the categories of the feed. At the feed level, it is almost always one category that defines the kind of the feed (video feed, related feed,etc). The entry() uses this information to load the proper class, ie Video or Comment entries.

    Parameters

    none - getter

    Returns

    categories:Collection - WebService::GData::Collection containing WebService::GData::Node::Category.

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        my $categories = $feed->category();
        foreach my $category (@$categories) {
            #$category->scheme,$category->term,$category->label
        }
        
        #search for a particular kind of category
        my $kind = $categories->scheme('kind')->[0];
        
        #json feed category is as below:
        "category": [
          {
           "scheme": "http://schemas.google.com/g/2005#kind",
           "term": "http://gdata.youtube.com/schemas/2007#video"
          }
        ]
          

etag

    Get the etag of the feed. The etag is a unique identifier key to track updates to the document.

    Parameters

    none - getter

    Returns

    etag:Scalar - the etag value

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
       $feed->etag();#W/\"CkICQX45cCp7ImA9Wx5XGUQ.\"
       

    See also http://code.google.com/intl/en/apis/gdata/docs/2.0/reference.html#ResourceVersioning for further information about resource versioning.

author

    Get the author of the feed.

    Parameters

    none - getter

    Returns

    author:Collection - WebService::GData::Collection containing WebService::GData::Node::AuthorEntity.

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
       my $authors=  $feed->author();
       
       foreach my $author (@$authors){
           #$author->name,$author->uri
       }
       
       #raw json feed:
       
       "author": [
         {
           "name": {
            "$t": "YouTube"
           },
           "uri": {
            "$t": "http://www.youtube.com/"
           }
          }
        ],
       

The following methods sent back information that can be useful to paginate the result. You get access to the number of result, the number of item sent and the offset from which the result start.

total_items

    Get the total result of the feed.

    Parameters

    none - getter

    Returns

    total_items:Int - the total number of items

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        $feed->total_items();#1000000
        

total_results

    Get the total result of the feed. Alias for total_items

    Parameters

    none - getter

    Returns

    total_results:Int - the total number of items

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        $feed->total_results();#1000000
        

start_index

    Get the start number of the feed.

    Parameters

    none - getter

    Returns

    start_index:Int - the start index of the feed counting from 1.

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        $feed->start_index();#1
        

items_per_page

    Get the the number of items sent per result.

    Parameters

    none - getter

    Returns

    items_per_page:Int - the number of item in the result.

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        $feed->items_per_page();#25
        

    Get the links of the feed in a array reference.

    Parameters

    none - getter

    Returns

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        my $links = $feed->links();
        foreach my $link (@$links){
            #link->rel,$link->type,$link->href
        }
        
        #raw json data:
        
          "link": [
           {
            "rel": "alternate",
            "type": "text/html",
            "href": "http://www.youtube.com"
           },
           {
            "rel": "http://schemas.google.com/g/2005#feed",
            "type": "application/atom+xml",
            "href": "http://gdata.youtube.com/feeds/api/videos"
           },
           {
            "rel": "http://schemas.google.com/g/2005#batch",
            "type": "application/atom+xml",
            "href": "http://gdata.youtube.com/feeds/api/videos/batch"
           }
          ]
        

    Get a specific link entry by looking in the rel attribute of the link tag.

    Parameters

    Returns

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
    
        my $previous_url= $feed->get_link('previous');
        
        my $batch_url   = $feed->get_link('batch');

    Get a the previous link if set or undef. Shortcut for $feed->get_link('previous');

    Get a the next link if set or undef. Shortcut for $feed->get_link('next');

entry

    This method return an array reference of Feed::* objects.

    It works as a factory by instantiating the proper Feed::* class.

    For example,if you read a video feed from a youtube service, it will instantiate the WebService::GData::Youtube::Feed::Video class and feed it the result.

    It will look first at the category scheme set in the feed or at the entry category scheme that contains the base schema name of the feed.

    If it does not guess properly,you can always specify the name of the package to load as its first argument.

    Parameters

    class_name::Scalar* - (optional) Force a specific class to be loaded and do not let entry guess the feed type on its own.

    Returns

    entries:ArrayRef - By default it uses WebService::GData::Entry::Feed but will return instances of the found package or of the specified one

    Example:

        use WebService::GData::Feed;
        
        my $feed = new WebService::GData::Feed($jsonfeed);
        
        my $entries = $feed->entry('WebService::GData::Feed::Entry');#force a particular class to be used
        my $entries = $feed->entry();#let entry figure it out by looking at the feed meta information.
        
        foreach my $entry (@$entries) {
            
            #$entry->title,$entry->id... all entry sub classes should inherit from WebService::GData::Feed::Entry
        }   

JSON FEED EXAMPLE

Below is a raw json feed example from querying youtube videos. Only the relevant parts are listed.

The actual feed does contain more information but a possible switch to JSONC, freed of meta information, being possible, this package only offers wrapper methods to what is relevant in the JSONC context.

    {
     "feed": {
      "gd$etag": "W/\"CkICQX45cCp7ImA9Wx5XGUQ.\"",
      "id": {
       "$t": "tag:youtube.com,2008:videos"
      },
      "updated": {
       "$t": "2010-09-20T13:49:20.028Z"
      },
      "category": [
       {
        "scheme": "http://schemas.google.com/g/2005#kind",
        "term": "http://gdata.youtube.com/schemas/2007#video"
       }
      ],
      "title": {
       "$t": "YouTube Videos"
      },
      "link": [
       {
        "rel": "alternate",
        "type": "text/html",
        "href": "http://www.youtube.com"
       },
       {
        "rel": "http://schemas.google.com/g/2005#feed",
        "type": "application/atom+xml",
        "href": "http://gdata.youtube.com/feeds/api/videos"
       },
       {
        "rel": "http://schemas.google.com/g/2005#batch",
        "type": "application/atom+xml",
        "href": "http://gdata.youtube.com/feeds/api/videos/batch"
       },
       {
        "rel": "self",
        "type": "application/atom+xml",
        "href": "http://gdata.youtube.com/feeds/api/videos?alt=json&start-index=1&max-results=25"
       },
       {
        "rel": "service",
        "type": "application/atomsvc+xml",
        "href": "http://gdata.youtube.com/feeds/api/videos?alt\u003datom-service"
       },
       {
        "rel": "next",
        "type": "application/atom+xml",
        "href": "http://gdata.youtube.com/feeds/api/videos?alt=json&start-index=3&max-results=25"
       }
      ],
      "author": [
       {
        "name": {
         "$t": "YouTube"
        },
        "uri": {
         "$t": "http://www.youtube.com/"
        }
       }
      ],
      "openSearch$totalResults": {
       "$t": 1000000
      },
      "openSearch$startIndex": {
       "$t": 1
      },
      "openSearch$itemsPerPage": {
       "$t": 25
      },
      "entry": [....]#erased as there are implemented in each sub classes
     }
    }

BUGS AND LIMITATIONS

If you do me the favor to _use_ this module and find a bug, please email me i will try to do my best to fix it (patches welcome)!

AUTHOR

shiriru <shirirulestheworld[arobas]gmail.com>

LICENSE AND COPYRIGHT

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

4 POD Errors

The following errors were encountered while parsing the POD:

Around line 606:

You forgot a '=back' before '=head3'

Around line 641:

You forgot a '=back' before '=head3'

Around line 647:

You forgot a '=back' before '=head3'

Around line 655:

You forgot a '=back' before '=head3'