Community contributed extensions

Facebook Graph API Support

The FbGraph module enables your application to access all the features of the Facebook Graph API via Java and the Play framework. It uses the Facebook JavaScript SDK to provide simple login and signup.

Prerequisites

The FbGraph module requires that you register your application with Facebook to get an App ID (or appId) for your site.

Installation and Configuration

Start by installing the FbGraph module from the modules repository:

play install fbgraph-{version}

Then, edit the dependencies.yml file to add the module as dependency of your application:

require:
    - play -> fbgraph {version}:
        transitive: false

Finally, configure the module by setting these properties in your application.conf:

# FbGraph
# ~~~~~
fbg.appId={YOUR_APP_ID}
fbg.appSecret={YOUR_APP_SECRET}

Login

Fbg Script Tag (for loading the Facebook JavaScript SDK)

The FbGraph module provides a tag for loading the Facebook JavaScript SDK. It uses the standard script element, calls FB.init() and specifies a <div> element named fb-root within the document.

First, include the following tag in your page:

#{fbg.script /}

Facebook XML Mamespace

Next, add an XML namespace attribute to the root <html> element of your page in order to use the XFBML tags:

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">

Facebook Login Button

Then, add the standard Facebook Login Button to your page using the <fb:login-button> XFBML element:

<fb:login-button onlogin="facebookLogin();"></fb:login-button>

If you need access to more information, such as the user’s birthday or wall, you must request permissions. You can do this by adding the permissions you need to the perms attribute of the <fb:login-button> (e.g. perms="email,user_birthday,read_stream,publish_stream").

Note: A full list of permissions is available here.

JavaScript Function and Controller Action Method

Finally, implements a JavaScript function that will be called if the Facebook login is successful:

<script type="text/javascript">
    function facebookLogin() {
        // get current login status from facebook.com
        FB.getLoginStatus(function(response) {
            if (response.session) {
                // logged in and connected user, someone you know
                window.location = "@{Application.facebookLogin()}";
            } else {
                window.location = "@{Secure.logout()}";
            }
        });
    }
</script>

In this example, the application will redirect the browser to the action /application/facebookLogin. The URL will invoke the controllers.Application.facebookLogin() action method. In this action, you can do useful things like retrieving an object of the domain class that represents a user (or create one if it doesn’t exist) and put the user’s name into the session:

// [...]
import play.modules.facebook.FbGraph;
import play.modules.facebook.FbGraphException;
import play.modules.facebook.Parameter;
// [...]
public class Application extends Controller {
// [...]
    public static void facebookLogin() {
        try {
            JsonObject profile = FbGraph.getObject("me"); // fetch the logged in user
            String email = profile.get("email").getAsString(); // retrieve the email
            // do useful things
            Session.current().put("username", email); // put the email into the session (for the Secure module)
        } catch (FbGraphException fbge) {
            flash.error(fbge.getMessage());
            if (fbge.getType() != null && fbge.getType().equals("OAuthException")) {
                Session.current().remove("username");
            }
        }
        redirect("/");
    }
}
// [...]

API Calls / Examples

Reading

// Objects
JsonObject user             = FbGraph.getObject("btaylor");
JsonObject page             = FbGraph.getObject("cocacola");

// Connections
JsonArray friends           = FbGraph.getConnection("me/friends");
JsonArray newsFeed          = FbGraph.getConnection("me/home");

// Selection
JsonObject fields           = FbGraph.getObject("bgolub", Parameter.with("fields", "id,name,picture").parameters());
JsonElement ids             = FbGraph.api("", Parameter.with("ids", "arjun,vernal").parameters());

// Picture
String profilePicUrl        = FbGraph.getPicture("me");

// Paging
JsonArray filteredLikes     = FbGraph.getConnection("me/likes", Parameter.with("limit", "3").parameters());
JsonArray filteredSearch    = FbGraph.getConnection("search", Parameter.with("until", "yesterday").and("q", "orange").parameters());

Searching

// Public search
JsonArray publicPostSearch  = FbGraph.getConnection("search", Parameter.with("q", "watermelon").and("type", "post").parameters());
JsonArray publicUserSearch  = FbGraph.getConnection("search", Parameter.with("q", "mark").and("type", "user").parameters());

Publishing

JsonElement post            = FbGraph.publish("me/feed", Parameter.with("message", "Hello World!").parameters());

Deleting

Boolean deleted             = FbGraph.delete("OBJECT_ID");

Analytics

JsonArray data              = FbGraph.getConnection("APP_ID/insights");

JSON to Java Objects

The FbGraph module provides simple methods to convert JSON to arbitrary Java Objects (including pre-existing objects) using the Gson library.

The JSON string returned by Facebook can be mapped to a Java Object like the following:

User user = FbGraph.getObject("btaylor", User.class);

For custom naming policy, you can use the SerializedName annotation on the members of the model class.

public class User {
    private String id;
    private String name;
    @SerializedName("last_name")
    private String familyName;
    @SerializedName("first_name")
    private String givenName;
    private String gender;
    private String birthday;
    private String email;
    // [...]
    // Getters and setters
}

RestFB Client Alternative

The module also provides a RestFB client that you can invoke like this:

// User login using the RestFB client
public static void facebookLogin() {
    com.restfb.FacebookClient fbClient = FbGraph.getFacebookClient();
    com.restfb.types.User profile = fbClient.fetchObject("me", com.restfb.types.User.class);
    String email = profile.getEmail();
    // do useful things
    Session.current().put("username", email);
    redirect("/");
}

Fbg Script Tag Options

Loading the SDK Asynchronously

#{fbg.scriptAsync /}

Internationalization

#{fbg.script locale: 'fr_CA' /}

Default: en_US

SSL

#{fbg.script ssl: 'true' /}

Default: false

Access Token

An access token enables you (or your application) to access the user’s information and take actions on their behalf. FbGraph module retrieves this user access token from the cookie created by Facebook for your App ID. With a valid access token, FbGraph can invoke the Graph API by appending the access_token parameter to the requests.

If you want to specify your own access token, you can do it by passing the token as a parameter of the API call:

JsonObject user = FbGraph.getObject("btaylor", Parameter.with("access_token", "YOUR_ACCESS_TOKEN").parameters());

Known Issues