Fb:ref
From Facebook Developer Wiki
Contents |
Description
Fetches and renders content (like FBML or JavaScript) from a given ref source onto your canvas pages. The ref source is either a ref string "handle" you've created using fbml.setRefHandle or a URL that serves the content.
You can use this to improve performance of canvas pages, because Facebook caches the content included in the fb:ref tag.
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 content. 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 content. You must specify either url or handle, but not both. |
Examples
When using key/value pairs, Facebook stores developer-specified content on its servers in the form of a hashtable.
To set the content for YourHandle, you must call fbml.setRefHandle at least once.
fbml.setRefHandle("YourHandle", "FBML_Content")
Next, include the content 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 content, passing it to the user.
To include the specified content, 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).
