NAME

Image::Randim::Source::Role - Source plugins must implement this role

SYNOPSIS

            

              
              
package Image::Randim::Source::Desktoppr
use Moose;
has 'name' => ( is  => 'ro',
  isa => 'Str',
  default => 'Desktoppr',
    );
has 'url' => ( is  => 'ro',
 isa => 'Str',
 default => 'https://api.desktoppr.co/1/wallpapers/random',
    );
with 'Image::Randim::Source::Role';
sub get_image {
    my $self = shift;
    my $data = JSON->new->decode($self->get_response);
    $data = $$data{'response'};
    my $image = Image::Randim::Image->new(
 url    => $$data{'image'}{'url'},
 id     => $$data{'id'},
 width  => $$data{'width'},
 height => $$data{'height'},
 link   => $$data{'url'},
 );
    if (exists $$data{'uploader'}) {
 $image->owner($$data{'uploader'});
    }
    return $image;
}
            
          

DESCRIPTION

To create a source "plugin" for this library, the plugin must be a Moose class which implements this role and is named in the Image::Randim::Source::* namespace.

The class must provide "name", "url" and "get_image" methods or attributes. "timeout" and "get_response are provided as a convience in the role but may be overridden.

ROLE INTERFACE

name

Plugins must return a name, which is a string representing the source (such as "Desktoppr").

This name must be the same as the name of module's end. For example, in the case of the module "Image::Randim::Source::Desktoppr", the name must be "Desktoppr".

url

Plugins must return a URL, which is a string representing the link that must be called on the provider's site to get the random image's data.

This is typically a API call that returns JSON.

get_image

Plugins must return an Image::Randim::Image object, which is populated with the information retrieved from the URL call to the provider.

In the SYNOPSIS example, you see that JSON is returned from the get_response() call to the provider's API (which uses the provided url()) -- and then that JSON is parsed into a hash that is used to set the image object attributes, and return it.

timeout($integer)

How many seconds to wait for a response from the provider's site. This value is up to the individual plugins to honor, but the provided convenience method "get_response" honors it.

CONVENIENCE METHODS

get_response

Convenience method that will call the given "url" with a GET, and expect a JSON response within the "timeout" time period.

Whatever is returned can then be used to create that Image::Randim::Image object. Usually what is returned in JSON -- but your "get_image" method should handle this reponse and populate the image object accordingly.

AUTHOR

Mark Rushing <mark@orbislumen.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Home Grown Systems, SPC.

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