[Catalyst-commits] r12176 -
trunk/examples/CatalystAdvent/root/2009/pen
zamolxes at dev.catalyst.perl.org
zamolxes at dev.catalyst.perl.org
Thu Dec 3 23:23:47 GMT 2009
Author: zamolxes
Date: 2009-12-03 23:23:46 +0000 (Thu, 03 Dec 2009)
New Revision: 12176
Modified:
trunk/examples/CatalystAdvent/root/2009/pen/fbconnect.pod
Log:
facebook article - done
Modified: trunk/examples/CatalystAdvent/root/2009/pen/fbconnect.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2009/pen/fbconnect.pod 2009-12-03 23:06:54 UTC (rev 12175)
+++ trunk/examples/CatalystAdvent/root/2009/pen/fbconnect.pod 2009-12-03 23:23:46 UTC (rev 12176)
@@ -1,43 +1,46 @@
-=head1 FBConnect with Catalyst::Authentication::Credential::FBConnect
+=head1 Socialize with FBConnect
-L<Catalyst::Authentication::Credential::FBConnect> offers an easy way to grab the credential identifier, session key and session expires from a user on Facebook.
+=head2 FBWhat?
+According to Facebook, "Facebook Connect is a powerful set of APIs for developers
+that lets users bring their identity and connections everywhere." The idea is quite
+similar to Oauth or Yahoo's BBauth, but with a Facebook flavour.
-You'll have the following accessors in C<< $c->user >>
+You can read more technical stuff about it here:
-=over
+L<http://wiki.developers.facebook.com/index.php/Getting_Started_with_Facebook_Connect>
-=item
+Why would you need it? The simple scenario: you can use it like a bizarro openid, until
+facebook becomes an openid provider :) Some of you will just want this: "allow people to
+authenticate in my website using their facebook user"
-session_uid
+But once the user is authenticated, your Catalyst app may also access the Facebook API
+using your user's credentials. Assuming she gives you permission, you can do all kinds
+of tricks, like getting the list of friends, avatar and such.
-=item
+=head2 I want it, what now?
-session_key
+Easy, just use L<Catalyst::Authentication::Credential::FBConnect>. Once authenticated, will give you the
+facebook user identifier and the session key you can later use with L<WWW::Facebook::API>.
-=item
+First of all you need to signup as a developer and get an I<API Key>, a I<Secret> and an
+I<Application Name>. You'll need these to use Facebook connect in Catalyst. Do you're thing
+at L<http://developers.facebook.com> and come back with the info.
-session_expires
+Then make sure you fetch you have our credential installed.
+L<Catalyst::Authentication::Credential::FBConnect> depends on L<WWW::Facebook::API>, L<Moose>,
+L<MooseX::Types::Moose> and L<MooseX::Types::Common>
-=back
+=head1 Setting it up
-=head1 Instalation
+First thing, set up your Catalyst application. You should be familiar with authentication realms
+by now, if not, take a look at L<Catalyst::Plugin::Authentication>
-L<Catalyst::Authentication::Credential::FBConnect> depends on:
+If you use the FBConnect credential to authenticate, you don't even need a database in your app.
+But most of your time you'll want to associate the Facebook user to a local user, and allow users
+to also authenticate the standard, password-based way. That's why we'll need two realms, C<facebook>
+and C<dbic>.
-L<WWW::Facebook::API>
-
-L<Moose>
-
-L<MooseX::Types::Moose>
-
-L<MooseX::Types::Common>
-
-
-=head1 Getting it done
-
-
-
package MyApp;
__PACKAGE__->config( 'authentication' => {
@@ -48,7 +51,7 @@
class => 'FBConnect',
api_key => 'my_api_key',
secret => 'my_secret',
- app_name => 'my_app_name',
+ app_name => 'my_app_name',
}
},
dbic => {
@@ -66,6 +69,11 @@
} );
+The user table should have some columns for holding the external credential
+info, if you want to associate the two. We're using C<credential_identifier>
+to hold the facebook uid. If you're using multiple external authentication
+systems (like openid, oauth) it would be a good idea to specify the source
+for this particular credential ( C<credential_source> ).
package MyApp::Schema::Result::User;
use strict;
@@ -87,10 +95,12 @@
data_type => 'varchar',
is_nullable => 1
},
+
credential_identifier => {
data_type => 'varchar',
is_nullable => 1
},
+
credential_source => {
data_type => 'varchar',
is_nullable => 1
@@ -104,14 +114,20 @@
1;
+=head2 The login action
+The logic is simple: the first time you call C<< $c->authenticate >> for the C<facebook> realm ,
+the user will be redirected to the facebook login page. Once she manages to authenticate there,
+she will be send back by facebook to our application (in the same action), but accompanied by
+an C<auth_token> . When C<authenticate> is called this time, the user is authenticated and
+C<< $c->user >> is created with the session information. All this logic is abstracted away
+inside the credential.
- package MyApp::Controller::FBConnect;
- use strict;
- use warnings;
-
- use base 'Catalyst::Controller';
-
+Now, once she's authenticated with FBConnect, she'll either register or login (hence
+L<find_or_create>) in our internal user database. After that we'll just use the familiar
+API to reauthenticate the user in the C<dbic> realm.
+
+
sub login : Path('/login/facebook') {
my ($self, $c) = @_;
@@ -129,22 +145,15 @@
}
- 1;
+=head2 Connect an existing user
+You can also assign a facebook account to an already existing account
-You can also assign a facebook account to an already existing account.
-
-
- #somewhere in a password required login: $c->authenticate( { email => $email, password => $password }, 'foo' );
- package MyApp::Controller::FBconnect;
- use strict;
- use warnings;
-
sub assign : Path('/assign/facebook') {
my ($self, $c) = @_;
- my $user = $c->user if $c->user_in_realm('foo');
+ my $user = $c->user if $c->user_in_realm('dbic');
if( $c->authenticate( {}, 'facebook' ) ) {
$user->update( {
credential_identifier => $c->user->session_uid,
@@ -160,10 +169,10 @@
}
+=head2 Use the Facebook API
+All the work above gets you the uid from Facebook. This can be used later on with L<WWW::Facebook::API>.
-This practicaly gets you the uid from Facebook. This can be used later on with L<WWW::Facebook::API>.
-
Here's some example code to actualy use L<WWW::Facebook::API>
my $client = WWW::Facebook::API->new(
@@ -185,4 +194,13 @@
-More about this can be found in the L<WWW::Facebook::API> docs
+But more about this can be found in the L<WWW::Facebook::API> docs, enjoy :)
+
+=head1 AUTHOR
+
+Cosmin Budrica <cosmin at sinapticode.com>
+
+=head3 COPYRIGHT
+
+Copyright 2009 Sinapticode - L<http://www.sinapticode.com>
+
More information about the Catalyst-commits
mailing list