Fb:ref
From Facebook Developer Wiki
Contents |
Description
Fetches and renders FBML from a given ref source – either a ref string "handle" you've created using fbml.setRefHandle or a URL that serves FBML. You can use this ref to publish identical FBML to a large number of user profiles and subsequently update those profiles, without having to republish FBML on behalf of each user (that is, using profile.setFBML for each user). For a high level discussion of the benefits of fb:ref and how to use it, read this forum post
Attributes
| Required | Name | Type | Description | |
| required | url | string | The URL from which to fetch the FBML. Facebook caches the content retrieved from that URL until you call fbml.refreshRefUrl. You must specify either url or handle, but not both. | |
|---|---|---|---|---|
| handle | string | The string previously set by fbml.setRefHandle that identifies the FBML. You must specify either url or handle, but not both. |
Examples
When using key/value pairs, Facebook stores developer-specified FBML on its servers in the form of a hashtable.
To set the FBML code of YourHandle, you must call fbml.setRefHandle at least once.
fbml.setRefHandle("YourHandle", "FBML_Content")
Next, include the FBML referenced by the handle. Insert the <fb:ref> tag into the appropriate place in your markup:
When using fb:ref with the url attribute, Facebook downloads the specified URL, caches the result, and parses the FBML, passing it to the user.
To include the specified FBML, insert the <fb:ref> tag into the appropriate place in your markup:
<fb:ref url="http://www.mysite.com/someurl.php" />
To clear the cache, call fbml.refreshRefUrl:
fbml.refreshRefUrl("http://www.mysite.com/someurl.php")Notes
Performance
If you have to update a large number of refs, you want to be using handle refs, since you can do it with a single push, rather than URL refs, which will hammer your server on the callback.[verify] You may also want to stream out your updates in parallel, which can be easily accomplished by using curl_multi instead of curl in the PHP5 facebook rest client. There's a guide available for this.
Cache Expiration
As mentioned within a forum thread by a member of the Facebook team: "You only need to publish on update. We'll keep it otherwise."
So the cache never expires and you will not need to periodically update your application cache. Facebook will keep the cache indefinitely. However, developers should not rely on the cache always keeping their data – i.e. it is not safe to assume that once data has been cached (in the case of a URL ref), it can be deleted from your server.
Nested Refs
The contents of a ref handle can contain FBML, including other <fb:ref> tags.
Warning: An infinite nesting can be created by creating two ref handles that refer to each other. Do not do this.
FBML Anomalies in Refs This writer has not been able to successfully create mock-Ajax forms inside of ref handles[possible bug?] (but that does not necessarily mean they don't work).
