/ 
Dancer-Plugin-Facebook-0.900
River stage zero No dependents
/ Dancer::Plugin::Facebook

NAME

Dancer::Plugin::Facebook - Manage Facebook interaction within Dancer applications

VERSION

version 0.900

SYNOPSIS

use Dancer;
use Dancer::Plugin::Facebook;

setup_fb;

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 as long as it applies. So you can use the fb object repeatedly during a request, even in different handlers, and be sure that it's not 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 an 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 you can use to retrieve and store the access_token when it is set.

USAGE

Basic usage

Load the module into your dancer application as you normally would:

use Dancer;
use Dancer::Plugin::Facebook;

This alone will configure the absolute bare minimum functionality, allowing you to make requests to Facebook's API for public information.

Registered application

If you have registered an application with Facebook, you should configure the module to use the relevant Application ID and Application Secret (see CONFIGURATION for details), and then call setup_fb within your application, like so:

use Dancer;
use Dancer::Plugin::Facebook;
setup_fb;

Authenticating users

If you wish for your application to be able to authenticate users using Facebook, you need to 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';

Acting on a user's behalf

If you wish for your application to be able to conncect to Facebook on behalf of a particular user, you need to additionally configure the permissions the application requires (see CONFIGURATION for details). Doing so implies that you will be "Authenticating users" as well; if you did not specify a mounting point when you called setup_fb, it will default to /auth/facebook.

CONFIGURATION

Your Dancer config.yml file plugins section should look something like this.

plugins:
  Facebook:
    application:
      app_id: XXXXXXXXXXXXXXX
      secret: XXXXXXXXXXXXXXX
    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 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.

The presence of a permissions list implies the setup of authentication. If an authentication URL is not specified when calling setup_fb, it will default to /auth/facebook.

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.