/ 
Dancer-Plugin-Adapter-0.002
River stage zero No dependents
/ Dancer::Plugin::Adapter

NAME

Dancer::Plugin::Adapter - Wrap any simple class as a service for Dancer

VERSION

version 0.002

SYNOPSIS

# in config.yml

plugins:
  Adapter:
    ua:
      class: HTTP::Tiny
      options:
        max_redirect: 3

# in your app

use Dancer::Plugin::Adapter;

get '/proxy/:url' => sub {
  my $res = service('ua')->get( params->{'url'} );
  if ( $res->{success} ) {
    return $res->{content};
  }
  else {
    template 'error' => { response => $res };
  }
};

DESCRIPTION

The problem: you want to use some perl class in your Dancer app, but there's no plugin for it.

The solution: as long as the class needs only static data to construct an object, then Dancer::Plugin::Adaptor can do the wrapping for you. Think of it as a "just-in-time" plugin (or maybe a poor-man's Bread::Board).

Here's another example: you want to send emails via Postmark using WWW::Postmark.

In your config.yml, you put this:

plugins:
  Adapter:
    postmark:
      class: WWW::Postmark
      options: POSTMARK_API_TEST

In your production config.yml, you can replace 'POSTMARK_API_TEST' with your real Postmark API key.

Then, in your application, here's how you use it:

get '/' => sub {
  eval {
    service("postmark")->send(
      from    => 'me@domain.tld',
      to      => 'you@domain.tld, them@domain.tld',
      subject => 'an email message',
      body    => "hi guys, what's up?"
    );
  };

  return $@ ? "Error: $@" : "Mail sent";
};

Dancer::Plugin::Adapter takes care of constructing and caching the WWW::Postmark object based on the configuration data, and lets you access the object with the service() function.

CONFIGURATION

One or more objects are defined by NAME => HASHREF pairs. The hash reference for each NAME must contain a 'class' key, whose value is the class to wrap.

If the hash reference contains an 'options' key, its value will be dereferenced (if it is a hash or array reference) and passed to new() when the object is created. Note that if the class requires a reference for the constructor, you have to wrap it in an extra array. E.g.

# config.yml:
plugins:
  Adapter:
    foo:
      class: Foo::Bar
      options:
        -
          wibble: wobble
          biff: boff

# constructor called as:
Foo::Bar->new( { wibble => wobble, biff => boff } );

If the class does not use 'new' as the name of its constructor, an alternate can be specified with the 'constructor' key.

# config.yml:
plugins:
  Adapter:
    tmpdir:
      class: File::Temp
      constructor: newdir

# constructor called as:
File::Temp->newdir()

USAGE

service

service($name);

This function returns the object corresponding to the name defined in the configuration file. The object is created on demand and cached for future use.

SEE ALSO

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/dancer-plugin-adapter/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/dagolden/dancer-plugin-adapter

git clone git://github.com/dagolden/dancer-plugin-adapter.git

AUTHOR

David Golden <dagolden@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2012 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004