by Dave Cohen: test facebook connect status on 403 and 404 pages.
[project/fb.git] / README.txt
CommitLineData
b1b8915b
DC
1Drupal for Facebook
2-------------------
186f033e 3
3cf45120 4Project Home:
49cb7c6f 5http://www.drupalforfacebook.org, http://drupal.org/project/fb
4e7ac9ba 6
b1b8915b 7Primary author and maintainer: Dave Cohen (http://www.dave-cohen.com/contact)
fdc2c009
DC
8Do NOT contact the maintainer with a question that can be easily
9answered with a web search. You may not receive a reply.
186f033e 10
fdc2c009 11Branch: master (version 3.x for Drupal 7.x)
186f033e 12
fdc2c009
DC
13This file is more current than online documentation. When in doubt,
14trust this file. Online documentation: http://drupal.org/node/195035,
15has more detail and you should read it next..
11d26016 16
3cf45120
DC
17To upgrade from Drupal 6 to Drupal 7:
18- Upgrade your D6 version to RC7 or later. Run update.php and make sure everything seems to work. Then upgrade drupal and all modules to D7 branch.
9bef2c4d 19
3cf45120
DC
20
21To upgrade from on D7 version to the next:
23d09493 22- Read the upgrade instructions: http://drupal.org/node/936958
6244c474
DC
23
24To install:
19092d2f 25
79bfec16
DC
26- Make sure you have a PHP client from facebook (version >= 3.1.1).
27 The 2.x.y versions are not supported by this version of Drupal for Facebook.
2c6c3675
DC
28 Download from http://github.com/facebook/php-sdk.
29 Extract the files, and place them in sites/all/libraries/facebook-php-sdk.
b1b8915b 30
49c58876
DC
31 If you have the Libraries API module installed, you may place the files in
32 another recognised location (such as sites/all/libraries), providing that the
33 directory is named 'facebook-php-sdk'.
b3adf089 34
79bfec16
DC
35 Or, to manually set the location of the php-sdk in any other
36 directory, edit your settings.php to include a line similar to the
37 one below. Add to the section where the $conf variable is defined,
38 or the very end of settings.php. And customize the path as needed.
49cb7c6f 39
2c6c3675 40 $conf['fb_api_file'] = 'sites/all/libraries/facebook-php-sdk/src/facebook.php';
186f033e 41
fdc2c009
DC
42 See also http://drupal.org/node/923804
43
b389f367
DC
44- To support canvas pages and/or page tabs, url rewriting and other
45 settings must be initialized before modules are loaded, so you must
46 add this code to your settings.php. This is done by adding these
47 two lines to the end of sites/default/settings.php (or
fdc2c009 48 sites/YOUR_DOMAIN/settings.php).
2c6c3675
DC
49
50 include "sites/all/modules/fb/fb_url_rewrite.inc";
9bef2c4d 51 include "sites/all/modules/fb/fb_settings.inc";
5fa5deaa 52
fdc2c009 53 (Change include paths if modules/fb is not in sites/all.)
d89700a9 54
b389f367
DC
55- Also for canvas pages, see http://drupal.org/node/933994 and search
56 for "P3P" to avoid a common problem on IE.
57
58- Go to Administer >> Site Building >> Modules and enable the Facebook
fdc2c009 59 modules that you need.
85fafe82 60
9bef2c4d 61 Enable fb.module for Social Plugins.
85fafe82 62
9bef2c4d 63 Enable fb_devel.module and keep it enabled until you have everything
3cf45120
DC
64 set up. You should disable this on your live server once you are
65 certain facebook features are working. (Note this requires
9bef2c4d
DC
66 http://drupal.org/project/devel, which is well worth installing
67 anyway.)
68
69 Enable fb_app.module and fb_user.module if you plan to create
70 facebook applications.
71
72 Enable fb_connect.module for Facebook Connect and/or
73 fb_canvas.module for Canvas Page apps.
74
3cf45120
DC
75 Create a new Text Format that does not restrict/clean HTML tags and use it
76 in blocks and nodes. Other Text Formats (formerly called Input Formats in D6)
77 like the built-in Full HTML Text Format actually mangle FB tags like <fb:like>.
78
fdc2c009
DC
79 Pages at http://drupal.org/node/932690 will help you decide which
80 other modules you need to enable for your particular needs.
9bef2c4d 81
329b36aa 82
fdc2c009
DC
83To support Facebook Connect, Canvas Pages, and/or Social Plugins that
84require an Application, read on...
0f4300e5 85
3cf45120 86- You must enable clean URLs. If you don't, some links that drupal
b1b8915b 87 creates will not work properly on canvas pages.
0f4300e5 88
b1b8915b 89- Create an application on Facebook, currently at
3cf45120
DC
90 http://www.facebook.com/developers/createapp.php. Fill in the
91 minimum required to get an apikey and secret. If supporting canvas
fdc2c009
DC
92 pages, specify a canvas name, too. You may ignore other settings
93 for now.
0f4300e5 94
fdc2c009
DC
95- Go to Administer >> Site Building >> Facebook Applications and click
96 the Add Applicaiton tab. Use the app id, apikey and secret that
97 Facebook has shown you. Hopefully other settings will be
98 self-explanitory. When you submit your changes, Drupal for Facebook
99 will automatically set the callback URL and some other properties
100 which help it work properly.
9bef2c4d
DC
101
102
11d26016 103Troubleshooting:
549aa675 104---------------
11d26016 105
b1b8915b 106Reread this file and follow instructions carefully.
11d26016 107
cdd91596 108Read http://drupal.org/node/933994, and all the module documentation
fdc2c009 109on http://drupal.org/node/912614.
cdd91596 110
9bef2c4d
DC
111Enable the fb_devel.module and add the block it provides (called
112"Facebook Devel Page info") to the footer of your Facebook theme.
fdc2c009
DC
113fb_devel.module will catch some errors and write useful information to
114Drupal's log and status page.
b1b8915b 115
b3adf089
DC
116Use your browser's view source feature, and search page source for any
117<script> tag which includes facebook's javascript,
118"http://connect.facebook.net/en_US/all.js". fb.js will include this
119for you. Including it too soon will break many features. So remove
120it from any block, node, template or whatever that adds it to the
121page. Similarly, do not include any <div id="fb-root">.
122
123Disable Global Redirect, if you have that module installed. Users
fdc2c009
DC
124have reported problems with it and Drupal for Facebook. Any module
125which implements custom url rewrites could interfere with canvas page
126and profile tab support.
47931800 127
ce9f6400
DC
128On the facebook side, make sure your application is not in "sandbox
129mode". This is known to have unwanted side effects. Also, don't use
130a test account. If you've used a test account, ever, even for another
131application, clear all your browser's cookies. Try to reproduce the
132problem not in sandbox mode, and not using a test account.
133
19092d2f 134Bug reports and feature requests may be submitted.
b1b8915b 135Here's an idea: check the issue queue before you submit
49cb7c6f 136http://drupal.org/project/issues/fb
b1b8915b
DC
137
138If you do submit an issue, start the description with "I read the
139README.txt from start to finish," and you will get a faster, more
3cf45120 140thoughtful response. Seriously, prove that you read this far.
06a3dd9f 141
3cf45120 142Below are more options for your settings.php. Add the PHP shown below
06a3dd9f 143to the very end of your settings.php, and modify the paths accordingly
fdc2c009 144(i.e. where this example has "sites/all/modules/fb", you might need
49cb7c6f 145"profiles/custom/modules/fb").
06a3dd9f 146
9bef2c4d
DC
147
148
149
2e854310 150//// Code to add to settings.php:
9bef2c4d 151/////////////////////////////////
06a3dd9f
DC
152
153/**
7efbb094 154 * Drupal for Facebook settings.
06a3dd9f
DC
155 */
156
157if (!is_array($conf))
158 $conf = array();
159
d89700a9 160$conf['fb_verbose'] = TRUE; // debug output
49cb7c6f 161//$conf['fb_verbose'] = 'extreme'; // for verbosity fetishists.
06a3dd9f 162
85fafe82 163// More efficient connect session discovery.
b324912a 164// Required if supporting one connect app and different canvas apps.
b3adf089 165//$conf['fb_id'] = '123.....XYZ'; // Your connect app's ID goes here.
66986115 166
85fafe82
DC
167// Enable URL rewriting (for canvas page apps).
168include "sites/all/modules/fb/fb_url_rewrite.inc";
9bef2c4d 169include "sites/all/modules/fb/fb_settings.inc";
06a3dd9f 170
85fafe82 171// end of settings.php