Dancer::Plugin::Adapter - Wrap any simple class as a service for Dancer
version 0.004
# in config.yml plugins: Adapter: ua: class: HTTP::Tiny scope: request 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 }; } };
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).
Dancer::Plugin::Adaptor
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 scope: singleton 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.
Dancer::Plugin::Adapter
service()
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.
NAME => HASHREF
The 'scope' key determines how long the generated object persists. The choice of scope will depend on whether the object holds onto any state that should not last across requests or users. The following scope values are allowed:
request -- (default) the object persists in the vars hash for the duration of the request
request
vars
singleton -- the objects persists in a private, lexical hash for the duration of the process
singleton
session -- the object persists in the session hash for the duration of the session
session
none -- the object is not cached; a fresh object is created on each call
none
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.
new()
# config.yml: plugins: Adapter: foo: class: Foo::Bar scope: request 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()
When caching under request or session scope, Dancer::Plugin::Adaptor uses the key _dpa in the vars or session hash, respectively.
_dpa
$object = service($name);
This function returns the object corresponding to the name defined in the configuration file. The object is created on demand and may be cached for future use based on its scope configuration option.
scope
Dancer
Dancer::Plugin
Thank you to Matt S. Trout for suggesting the 'scope' controls.
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.
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
David Golden <dagolden@cpan.org>
This software is Copyright (c) 2012 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install Dancer::Plugin::Adapter, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Dancer::Plugin::Adapter
CPAN shell
perl -MCPAN -e shell install Dancer::Plugin::Adapter
For more information on module installation, please visit the detailed CPAN module installation guide.