/ 
Dancer-Plugin-Facebook-0.991
++
 / Dancer::Plugin::Facebook
Michael Alan Dorman

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 using Facebook::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 and secret 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 the access_token for offline use when it is set. Then, simply store the access_token in session-{auth}->{facebook}> and the fb 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 and secret (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 to landing/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 the fb_redirect and fb_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-configured Facebook::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 file plugins 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 and secret keys in the application section correspond to the values available from the information page for your application.

The failure and success keys in the landing 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

Dancer

Facebook::Graph

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.