-
-
24 Sep 2012 19:40:54 UTC
- Distribution: Dancer-Plugin-Facebook
- Module version: 0.991
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (2)
- Testers (142 / 336 / 0)
- Kwalitee
Bus factor: 0- 35.88% Coverage
- License: perl_5
- Activity
24 month- Tools
- Download (12.87KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
NAME
Dancer::Plugin::Facebook - Manage Facebook interaction within Dancer applications
VERSION
version 0.991
SYNOPSIS
use Dancer; use Dancer::Plugin::Facebook; setup_fb '/auth/facebook'; get '/' => sub { fb->fetch ('16665510298')->{name}; } # returns 'perl'
DESCRIPTION
Dancer::Plugin::Facebook
is intended to simplify usingFacebook::Graph
from within a Dancer application.It will:
- manage the lifecycle of the Facebook::Graph object
-
The plugin goes to great lengths to only create the
Facebook::Graph
object when needed, and tries hard to cache it for as long as it it is valid, so you can use the fb object repeatedly during a request, even in different handlers, without it being rebuilt needlessly. - store your applications registration information in a single place
-
Though it's not required that you have an registered app, if you do, you need only record the
app_id
andsecret
in one place. - automatically create routes for handling authentication
-
If you pass a path to the
setup_fb
routine, the plugin will create the routes necessary to support authentication in that location. - automatically manage user authentication tokens
-
It will transparently manage them through the user session for you, collecting them when the user authenticates, and making sure that they are used when creating the
Facebook::Graph
object if they're present.There is also a hook available (
fb_access_token_available
) you can use to retrieve and store theaccess_token
for offline use when it is set. Then, simply store theaccess_token
insession-
{auth}->{facebook}> and thefb
object will automatically pick it up on each request.
USAGE
Basic usage
At its absolute most basic usage, you can simply load the module into your dancer application:
use Dancer; use Dancer::Plugin::Facebook;
This will configure the absolute bare minimum functionality, allowing you to make requests to Facebook's API for public information and nothing else.
Registered application
If you have registered an application with Facebook, you will need to configure the module to use the relevant
app_id
andsecret
(see CONFIGURATION for details), and you will need to call the setup_fb routine:use Dancer; use Dancer::Plugin::Facebook; setup_fb;
In all other respects, the usage is the same as the basic usage.
Authenticating users (simple)
If you're using Facebook for authentication, you may specify a point where the necessary web routes can be mounted when you call
setup_fb
, like so:use Dancer; use Dancer::Plugin::Facebook; setup_fb '/auth/facebook';
You should configure the module know where to redirect the user in the event of success or failure by configuring the
landing
parameters (see CONFIGURATION for details).To authenticate a user, simply redirect them to
/auth/facebook
, and when the user has been authenticated with Facebook, they will be redirected tolanding/success
(which is/
by default).Authenticating users (more configurable URLs)
If you absolutely need to set specific URLs for the redirection and postback pages, you can do this by setting up the routes yourself.
Do not specify a URL when calling
setup_fb
, and then use thefb_redirect
andfb_postback
functions to create your routes:use Dancer; use Dancer::Plugin::Facebook; setup_fb; get '/a/complicated/facebook/redirect/url' => fb_redirect; get '/a/postback/url/in/a/totally/different/place' => fb_postback '/a/postback/url/in/a/totally/different/place';
Please note, you do need to specify the postback URL as a parameter to
fb_postback
. It's ugly, but unavoidable as far as I can tell.Authenticating users (handling redirection when using AJAX)
If you are using AJAX to interoperate with your application, returning a 30X redirect code to push the user to Facebook may not work the way you expect. So, if necessary, you can just get back the appropriate URL, and send that to your client in some way it will interpret properly.
use Dancer; use Dancer::Plugin::Facebook; setup_fb; post '/auth' => sub { ... do some stuff to decide if you are supposed to even hit fb ... # hypothetically encoded as JSON and parsed by client app return {redirect => fb_redirect_url}; }; get '/auth/facebook/postback' => fb_postback '/auth/facebook/postback';
Please note, you do need to specify the postback URL as a parameter to
fb_postback
. It's ugly, but unavoidable as far as I can tell.Acting on a user's behalf (while logged in)
If you wish for your application to be able to access Facebook on behalf of a particular user while the user is logged in, you simply need to additionally configure the permissions the application requires (see CONFIGURATION for details).
Then, when the user has authenticated (and accepted your request for additional authorization), you may use the
fb
function to get a pre-configuredFacebook::Graph
object that will allow appropriate access:use Dancer; use Dancer::Plugin::Facebook; setup_fb '/auth/facebook'; get '/userinfo' => sub { my $user = fb->fetch ('me'); }
Acting on a user's behalf (offline)
If you wish for your application to be able to access Facebook on behalf of a particular user while the user is offline, you will need to additionally configure the permissions the application requires (see CONFIGURATION for details) to include
offline_access
Then, when the user has authenticated (and accepted your request for additional authorization), you should make sure to store the
access_token
that the authentication process returned and place it in stable storage for later use:use Dancer; use Dancer::Plugin::Facebook; setup_fb '/auth/facebook'; hook fb_access_token_available => sub { my ($token) = @_; ... store $token to DB --- }
CONFIGURATION
Your Dancer
config.yml
fileplugins
section should look something like this.plugins: Facebook: application: app_id: XXXXXXXXXXXXXXX secret: XXXXXXXXXXXXXXX landing: failure: /error success: / permissions: - create_event - email - offline_access - publish_stream - rsvp_event
The
app_id
andsecret
keys in theapplication
section correspond to the values available from the information page for your application.The
failure
andsuccess
keys in thelanding
section point to the URL(s) to redirect to upon success or failure in authenticating. If they're not present, they both default to/
.The
permissions
key includes a list of additional permissions you may request at the time the user authorizes your application. Facebook maintains a full list of available extended permissions.SEE ALSO
AUTHOR
Michael Alan Dorman <mdorman@ironicdesign.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 by Michael Alan Dorman.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
Module Install Instructions
To install Dancer::Plugin::Facebook, copy and paste the appropriate command in to your terminal.
cpanm Dancer::Plugin::Facebook
perl -MCPAN -e shell install Dancer::Plugin::Facebook
For more information on module installation, please visit the detailed CPAN module installation guide.