view release on metacpan or  search on metacpan

lib/Dancer/Plugin/Facebook.pm  view on Meta::CPAN

register fb => \&_get_fb;
register fb_redirect => \&_do_fb_redirect;
register fb_redirect_url => \&_get_fb_redirect_url;
register fb_postback => \&_do_fb_postback;
register_plugin;


1;

__END__
=pod

=head1 NAME

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

=head1 VERSION

version 0.991

=head1 SYNOPSIS

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

  setup_fb '/auth/facebook';

  get '/' => sub {
    fb->fetch ('16665510298')->{name};
  } # returns 'perl'

=head1 DESCRIPTION

C<Dancer::Plugin::Facebook> is intended to simplify using
C<Facebook::Graph> from within a Dancer application.

It will:

=over

=item manage the lifecycle of the Facebook::Graph object

The plugin goes to great lengths to only create the C<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.

=item 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 C<app_id> and C<secret> in one place.

=item automatically create routes for handling authentication

If you pass a path to the C<setup_fb> routine, the plugin will create
the routes necessary to support authentication in that location.

=item 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 C<Facebook::Graph> object if they're present.

There is also a hook available (C<fb_access_token_available>) you can
use to retrieve and store the C<access_token> for offline use when it
is set.  Then, simply store the C<access_token> in
C<session->{auth}->{facebook}> and the C<fb> object will automatically
pick it up on each request.

=back

=head1 USAGE

=head2 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.

=head2 Registered application

If you have registered an application with Facebook, you will need to
configure the module to use the relevant C<app_id> and C<secret> (see
L<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.

=head2 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
C<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 C<landing> parameters
(see L<CONFIGURATION> for details).

To authenticate a user, simply redirect them to C</auth/facebook>, and
when the user has been authenticated with Facebook, they will be
redirected to C<landing/success> (which is C</> by default).

=head2 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.