UsageNotes/Forms
From Facebook Developer Wiki
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:
Would expand to HTML something similar to:
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
requireloginon 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.
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.
