Class: Connect

Connect

new Connect(options)

Facebook login helper

When instantiated the class automatically asynchronously loads the FB SDK.

After the FB SDK is loaded and the DOMContentLoaded event fires the init method of the class. This method initializes the FB SDK, checks the current user's status (connected, not_authorized or uknown).

Based on this status a corresponding event of login, not_authorized or logout is dispatched.

If the status of the user changes then associated events are dispatched as well.

Based on options set for "login" and "logout" buttons necessary functionality is assigned to those.

Parameters:
Name Type Description
options Object

See defaultInitOptions
Since:
  • 1.0.0
Source:
Fires:

Extends

Members

defaultInitOptions :Object

The default initialization options.

Those options include:

  • appId (string) -- the only required option

    If you do not pass that none of the functionality will get executed.

  • xfbml (boolean) -- default value us true

    Simply forwarded to FBs SDK, denoting whether XFBML tags on the page should be parsed.

  • version (string) -- default value is 'v2.7'

    Another option passed to FBs SDK. This denotes that your code would expect functionality for that version of the API.

  • scope (string) -- default value is 'public_profile,email'

    You should pass a string with comma delimited permissions that your application needs as the scope option.

    Note that requesting permissions is not equal to receiving them. Facebook allows users to connect to your application providing access to just some of the information you've asked for. So if you're calling an API method that relies on special permissions it is a good idea to always double-check them.

    The api method of the class has a built-in way to double-check permissions, so just pass a string of those when calling it.

    Also, requesting too much permissions from the start may cause users reject your application (in case they are not acquainted with the option to simply disable them -- few users are).

    It is advised that the original login only requires some basic public profile information for the users and when you get to a meaningful situation where you need the permissions for some API method -- you can double check for the permissions even if those were not originally present in the scope option. This will just ask the users for additional permissions.

  • loginButton (string) -- default value is '.login'

    Pass a CSS selector for the loginButton option to hook proper login event handlers to the button.

  • logoutButton (string) -- default value is '.logout'

    Similar to the loginButton one.

  • locale (string) -- default value is 'en_US'

    This is used when building the URL for the FB SDK to load.

    The SDK is available as multiple languages at different URLs, so you need to load the proper one in order for your application to be localized.

    You can pass a locale here as '{language_code}_{country_code}' where {language_code} is a two-lowercase representation of the language (for example 'en' or 'pt') and {country_code} is a two-lowercase representation of the country (for example 'US' or 'GB' in case for English and 'BR' or 'PT' for Portuguese).

  • userBodyClass (string) -- default value is 'user'

    This class is assigned to the body tag after successful connection to the user's account is established.

  • guestBodyClass (string) -- default value is 'guest'

    This class is assigned to the body tag if a user logs out of FB when on the site or if they do not authorize the application.

  • onConnected() (callback)

  • onLogout() (callback)

  • onNotAuthorized() (callback)

There are three options that should be used as callback functions: onConnected(), onLogout() and onNotAthorized(). Those are called respectively when the user logs-in, when he logs-out and when the page is loaded by a user who has loged-into Facebook but has not yet authenticated your application.

Note that the onNotAuthorized() callback is executed on initialization of the Connect class (pretty-much on page load), so it may be annoying to the user to prompt them to log in right away.

Type:
  • Object
Source:

events :Object

Object storing all event types.

Each event type is an array of callback functions that get executed when an event of that type of dispatched.

Type:
  • Object
Inherited From:
Source:

options :Object

Initialization options

Type:
  • Object
Source:
See:

(private, inner) domReady :Boolean

Type:
  • Boolean
Source:

(private, inner) fbReady :Boolean

Type:
  • Boolean
Source:

(private, inner) initialized :Boolean

Type:
  • Boolean
Source:

Methods

addEventListener(eventType, callback) → {void}

Attaches an event handler to a specific event type

Parameters:
Name Type Description
eventType string

The type of the event you'd like to listen for
callback function

The function to be executed when the event occurs
Inherited From:
Source:
Returns:
Type
void

api(method, callback, doubleCheckPermissions) → {void}

Helper method for accessing FB.api

Parameters:
Name Type Description
method string

The api method you'd like to call. Use RESTful path.
callback function

The callback function to handle the result of the API call.
doubleCheckPermissions string

(optional) Pass a string to double-check whether the necessary permissions for the API call are available. It is encouraged to always double-check special permissions when making API calls. If the permission is midding the method will automatically handle it and trigger a dialog screen to ask the user to grant the permission. This is essential as users may originally authenticate the application but remove specific permissions later on.
Source:
Returns:
Type
void

dispatchEvent(eventType, eventObj) → {void}

Fires an event on behalf of the object

Parameters:
Name Type Description
eventType string

The type of the event you'd like to fire
eventObj Event

The actual event object that will be passed to listener functions. This can be used to store additional information for the situation.
Inherited From:
Source:
Returns:
Type
void

getDomReady() → {boolean}

Getter for the domReady private property

Source:
Returns:

Whether the DOM is ready or not

Type
boolean

getFbReady() → {boolean}

Getter for the fbReady private property

Source:
Returns:

Whether the FB JS SDK has been loaded and initialized

Type
boolean

getInitialized() → {boolean}

Getter for the initialized private property

Source:
Returns:

Whether the FB Login has been initialized

Type
boolean

login() → {void}

You can manually call the login method.

If the user has not yet authorized the application they will see a popup asking them for permissions, according to the scope from the init options.

If the user is not logged-into Facebook the popup will first ask them to do so and only then they will see the permissions requirements.

If the user has previously logged-in this will just take a second and will fire the login event once connection is reestablished.

Source:
Returns:
Type
void

logout() → {void}

You can manualy call the logout method.

This will simply log a user out of Facebook. It will not de-authorize your application, restricting it from future access.

Source:
Returns:
Type
void

removeEventListener(eventType, callback) → {void}

Removes a previously attached event to a specific event type.

Parameters:
Name Type Description
eventType string

The type of the event you'd like to unbind a handler for
callback function

This must be a reference to the same Function object that has been set as a listener. Otherwise the removal will not take place.
Inherited From:
Source:
Returns:
Type
void

setDomReady()

Setter, which calls the getter as the value is auto-set.

Source:

setFbReady(ready)

Setter for the fbReady private property

Parameters:
Name Type Description
ready boolean

The new state for the property
Source:

(private, inner) handleLogin(response) → {void}

Parameters:
Name Type Description
response Object
Source:
Returns:
Type
void

(private, inner) handleLogout(response) → {void}

Parameters:
Name Type Description
response Object
Source:
Returns:
Type
void

(private, inner) handleNotAuthorized(response) → {void}

Parameters:
Name Type Description
response Object
Source:
Returns:
Type
void

(private, inner) init(e) → {void}

Parameters:
Name Type Description
e Object
Source:
Returns:
Type
void

Events

login

Event dispatched when the user's account is connected to the application.

This is called upon successful connection of the user's profile either in response to them clicking on the "login" button or as some other direct call of the login method.

Type:
  • Object
Properties:
Name Type Description
response Object

FB API's response
Source:

logout

Event dispatched when the user's account is disconnected from the application.

This is called upon successful disconnection of the user's profile either in response to them clicking on the "logout" button or as some other direct call of the logout method.

This does not mean the user has deauthorized the application, rather that they are simply logged-out of Facebook.

Type:
  • Object
Properties:
Name Type Description
response Object

FB API's response
Source:

not_authorized

Event dispatched when the user does not authorize the application.

When the "login" button is clicked or the login method is called directly a popup is shown to the user asking for authorization of the application.

If the user declines the application's authorization the not_authorized event will be dispatched.

Type:
  • Object
Properties:
Name Type Description
response Obect

FB API's response
Source: