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.