Skip to content
This repository has been archived by the owner on Jan 13, 2022. It is now read-only.

Commit

Permalink
No commit message
Browse files Browse the repository at this point in the history
  • Loading branch information
dpurdy committed Nov 20, 2010
1 parent 9f58447 commit 17135fa
Showing 1 changed file with 12 additions and 239 deletions.
251 changes: 12 additions & 239 deletions readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,239 +1,17 @@
Facebook Connect JavaScript SDK
Facebook JavaScript SDK
===============================

Facebook [Connect][Connect] is a set of APIs that make your application more
social. With it you gain access to:

1. Identity: name, photos, events and more -- [User][FQL_User].
2. Social Graph: friends and connections -- [Connection][FQL_Connection].
3. Stream: activity, distribution, and integration points within Facebook, like
stream stories and Publishers [UI Dialogs][UI Dialogs].

[Connect]: http://developers.facebook.com/connect "Facebook | Connect"
[FQL_User]: http://wiki.developers.facebook.com/index.php/User_(FQL) "FQL User Table"
[FQL_Connection]: http://wiki.developers.facebook.com/index.php/Connection_(FQL) "FQL Connection Table"
[UI Dialogs]: http://developers.facebook.com/docs/reference/javascript/FB.ui "UI Dialogs (to render dialogs like publish and share)"

This repository contains the open source JavaScript SDK that allows you to
utilize the above on your website. Except as otherwise noted, the Facebook
utilize Facebook on your website. Except as otherwise noted, the Facebook
Connect JavaScript SDK is licensed under the Apache Licence, Version 2.0
(http://www.apache.org/licenses/LICENSE-2.0.html)



Status
------

This is an *beta* release. In order to guide the development of the library
and allow you to freely inspect and use the source, we have open sourced the
client JavaScript SDK. At a high level, the SDK provides:

- Authentication & Authorization
- Ability to make API calls
- Ability to show UI dialogs
- XFBML Tags & Widgets
- Data Access Abstractions


Usage
-----

The [examples][examples] are a good place to start. Here's an example of
initializing ([FB.init()][FB.init]) the library with all the options turned on:

<div id="fb-root"></div>
<script src="http://connect.facebook.net/en_US/all.js"></script>
<script>
FB.init({
appId : 'YOUR APP ID',
status : true, // check login status
cookie : true, // enable cookies to allow the server to access the session
xfbml : true // parse XFBML
});
</script>

[examples]: http://github.com/facebook/connect-js/tree/master/examples/
[FB.init]: http://developers.facebook.com/docs/reference/javascript/FB.init

### Asynchronous Loading

For better performance, you should load the initial script itself in a
non-blocking manner. This will mean you have to be more conscious about how you
invoke anything in the `FB` namespace, as asynchronously loading the script can
cause it to arrive after your application scripts have been loaded. To make
this more convenient, the library looks for a **global** named `fbAsyncInit`.
If it exists, this function will be executed once the library has been loaded.
You should trigger all `FB` related logic from here. When using this approach,
you should put the code right *after the opening* `<body>` tag. This will allow
Facebook to initialize in parallel with the rest of your page.

<div id="fb-root"></div>
<script>
window.fbAsyncInit = function() {
FB.init({
appId : 'YOUR APP ID',
status : true, // check login status
cookie : true, // enable cookies to allow the server to access the session
xfbml : true // parse XFBML
});
};

(function() {
var e = document.createElement('script');
e.src = document.location.protocol + '//connect.facebook.net/en_US/all.js';
e.async = true;
document.getElementById('fb-root').appendChild(e);
}());
</script>

### Internationalization

Facebook Connect features are available many locales. You can replace the
`en_US` locale specifed above with one of the [supported Facebook
Locales][locales]. For example, to load up the library and trigger dialogs,
popups and widgets to be in Hindi (`hi_IN`), you can load the library from this
URL:

http://connect.facebook.net/hi_IN/all.js

[locales]: http://wiki.developers.facebook.com/index.php/Facebook_Locales

### SSL

Facebook Connect is also available over SSL. You should only use this when your
own page is served over `https://`. The library will rely on the current page
protocol at runtime. The SSL URL is the same, only the protocol is changed:

https://connect.facebook.net/en_US/all.js


Authentication & Authorization
------------------------------

Facebook Connect provides the great benefit of removing the registration
process by allowing the user to login to your site with their Facebook account.
This is achieved by sharing the logged in user state between
http://www.facebook.com/ and your site http://www.example.com/. A Connected
user remains logged in to your site as long as they are logged in to Facebook.

This means you get to skip a lot of the boring stuff when you're building your
hot new application. You don't need to create your own registration flow, and
your users don't have to create new profiles, upload profile pictures or
remember a username. But not only that, you also get the user's social graph,
and many other useful pieces of information. Facebook Connect can also be used
with your existing user management system as many sites already do.

### Status & Sessions

The first step is figuring out how you identify who the current user is, and
how to make API calls on their behalf. In fact, almost **half** of the public
API deals directly with auth:

- [FB.login()][FB.login] -- login and/or request extended permissions
- [FB.logout()][FB.logout] -- logout (only if the user is connected with your application)
- [FB.getLoginStatus()][FB.getLoginStatus] -- get current login status from facebook.com
- [FB.getSession()][FB.getSession] -- **synchronous** accessor for the current session

In addition, there many events that you can subscribe to using
[FB.Event.subscribe()][FB.Event.subscribe]:

- auth.statusChange
- auth.sessionChange
- auth.login
- auth.logout

[FB.login]: http://developers.facebook.com/docs/reference/javascript/FB.login
[FB.logout]: http://developers.facebook.com/docs/reference/javascript/FB.logout
[FB.getLoginStatus]: http://developers.facebook.com/docs/reference/javascript/FB.getLoginStatus
[FB.getSession]: http://developers.facebook.com/docs/reference/javascript/FB.getSession
[FB.Event.subscribe]: http://developers.facebook.com/docs/reference/javascript/FB.Event.subscribe


API Calls
---------

Facebook provides many server-side [APIs][API] to enable you to integrate data
from Facebook into your site, as well as allowing you to submit data into
Facebook. The JavaScript SDK makes all this available to you via
[FB.api()][FB.api]:

[FB.api]: http://developers.facebook.com/docs/reference/javascript/FB.api "Server-Side API Calls"

FB.api(
{
method: 'fql.query',
query: 'SELECT name FROM user WHERE uid=5526183'
},
function(response) {
alert('Name is ' + response[0].name);
}
);

[API]: http://wiki.developers.facebook.com/index.php/API


Dialogs
-------

One of the most powerful features of the SDK is to integrate Facebook UI flows
into your application. The most common example of this is the
**stream.publish** dialog. [FB.ui()][FB.ui] is the method that allows you to
trigger this and other dialogs. For example:

[FB.ui]: http://developers.facebook.com/docs/reference/javascript/FB.ui "UI Dialogs (to render dialogs like publish and share)"

FB.ui(
{
method: 'stream.publish',
attachment: {
name: 'Connect',
caption: 'The Facebook Connect JavaScript SDK',
description: (
'A small JavaScript library that allows you to harness ' +
'the power of Facebook, bringing the user\'s identity, ' +
'social graph and distribution power to your site.'
),
href: 'http://fbrell.com/'
},
action_links: [
{ text: 'fbrell', href: 'http://fbrell.com/' }
]
},
function(response) {
if (response && response.post_id) {
alert('Post was published.');
} else {
alert('Post was not published.');
}
}
);

UI dialogs are documented at TODO.


XFBML & Widgets
---------------

XFBML and Widgets provide a simple, low effort means of integrating social
features into your site. The current set of supported tags are:

- [fb:comments][fb:comments]
- [fb:fan][fb:fan]
- [fb:live-stream][fb:live-stream]
- [fb:login-button][fb:login-button]
- [fb:name][fb:name]
- [fb:profile-pic][fb:profile-pic]
- [fb:serverfbml][fb:serverfbml]
- [fb:share-button][fb:share-button]

[fb:comments]: http://wiki.developers.facebook.com/index.php/Fb:comments_(XFBML)
[fb:fan]: http://wiki.developers.facebook.com/index.php/Fb:fan
[fb:live-stream]: http://wiki.developers.facebook.com/index.php/Fb:live-stream
[fb:login-button]: http://wiki.developers.facebook.com/index.php/Fb:login-button
[fb:name]: http://wiki.developers.facebook.com/index.php/Fb:name
[fb:profile-pic]: http://wiki.developers.facebook.com/index.php/Fb:profile-pic
[fb:serverfbml]: http://wiki.developers.facebook.com/index.php/Fb:serverFbml
[fb:share-button]: http://wiki.developers.facebook.com/index.php/Fb:share-button_(XFBML)
client JavaScript SDK.

Documentation
-------------
Expand All @@ -253,7 +31,6 @@ The repository also contains simple [examples][examples] showing the use of the
SDK with popular JavaScript libraries such as [Dojo][Dojo], [jQuery][jQuery],
[MooTools][MooTools], [Prototype][Prototype] and [YUI][YUI].


[docs]: http://developers.facebook.com/docs/reference/javascript/ "Public API Documentation"
[Dojo]: http://www.dojotoolkit.org/
[jQuery]: http://jquery.com/
Expand All @@ -264,25 +41,21 @@ SDK with popular JavaScript libraries such as [Dojo][Dojo], [jQuery][jQuery],
[changelog]: http://github.com/facebook/connect-js/tree/master/changelog.md
[examples]: http://github.com/facebook/connect-js/tree/master/examples/



Feedback
--------

We are relying on the [GitHub issues tracker][issues] linked from above for
feedback. File bugs or other issues [here][issues].

[issues]: http://github.com/facebook/connect-js/issues



Tests
-----

We are working hard to ensure your experience using Connect is stable. In order
We are working hard to ensure your experience using the SDK is stable. In order
to keep us nimble and allow us to bring you new functionality, without
compromising on stability, we have ensured full test coverage of the new SDK.
We are including this in the open source repository to assure you of our
commitment to quality, but also with the hopes that you will contribute back to
help keep it stable. The easiest way to do so is to file bugs and include a
test case.

Feedback
--------

We are relying on the [GitHub issues tracker][issues] linked from above for
feedback. File bugs or other issues [here][issues].

[issues]: http://github.com/facebook/connect-js/issues

0 comments on commit 17135fa

Please sign in to comment.