UsageNotes/Forms

From Facebook Developer Wiki

Jump to: navigation, search

Facebook created an override for the HTML form tag to provide applications with special behavior. This override is for the fb:request-form FBML tag.

Using a form tag in FBML results in a number of hidden input tags being inserted into the generated HTML. The hidden tags provide information about the user submitting the form and the context in which the form was submitted. A signature allowing applications to verify that the form is being submitted from a Facebook page is also provided.

The FBML code:

<form></form>

Would expand to HTML something similar to:

<form> <input type="hidden" name="fb_sig_profile" value="1160"/> <input type="hidden" name="fb_sig_user" value="1160"/> <input type="hidden" name="fb_sig_session_key" value="b12d7f73fc47536b32e89e-1160"/> <input type="hidden" name="fb_sig_time" value="1176705186"/> <input type="hidden" name="fb_sig" value="773af1263c2b7bade7958e6b58d3152f"/> </form>


The fb_sig value is generated using all of the other fb_sig_* parameters (but without the fb_sig_ prefix included in their names) identically to how it is generated in the API authentication scheme. The fb_sig_user and fb_sig_session_key parameters will only be included if the user has a valid session with the application.

The form tag has an optional attribute requirelogin, which defaults to false. When it is true and a user without who hasn't authorized your application tries to submit the form, the user is prompted with a dialog to authorize your application. If the user authorizes it, Facebook then passes the fb_sig_user value to your application.

Notes

  • You cannot use any custom input elements with names that start with fb, as Facebook reserves that identifier.
  • You can use relative URLs in the form's action on application tabs and canvas pages. However, you must use absolute URLs for forms in profile boxes.
  • If you pass requirelogin on a form, then the form cannot contain any input element named submit, as the form won't get submitted correctly.
  • File uploads (that is, forms with enctype="multipart/form-data" and <input type="file"> fields) will not work when the form is submitted to a canvas URL. Instead, you need to submit file uploads directly to your application and redirect back to a canvas page after the form is processed.

Prompting a User for Extended Permissions

You can include the optional promptpermission attribute to prompt a user to approve an extended permission for your application. You specify the permission as a comma-separated string (one or more of email, read_stream, publish_stream, offline_access, status_update, photo_upload, create_event, rsvp_event, sms, video_upload, create_note, share_item).

When the user submits the form, and has not already granted this permission, the user is prompted to grant it. The form is always submitted, regardless of the user's response. The form also passes a hidden fb_perms parameter with the same value as specified in the promptpermission attribute. If the user grants the permission, another hidden parameter, fb_perms_approved, will be included with a value of 1. This attribute behaves similar to the requirelogin attribute in URLs.

The following sample code is from the Smiley sample application.

<p>Upon submitting the form below, you will be prompted to grant email permissions (unless you've already done so for this app): <form promptpermission="email"><br /> How often would you like to be notified of new smilies?<br /> <input type="text" name="frequency"> <input type="submit" value="Notify Me"> </form> </p>


Note: See Extended permissions for the various ways you can prompt a user for an extended permission.

Note: It seems this does not work on Connect-enabled websites (ed.: Correct. To prompt users for extended permissions from a Facebook Connect site, use FB.Connect.showPermissionDialog.

reference