From Facebook Developer Wiki

All Feed stories are generated from templates. You reference these templates in Feed forms, the Publisher, or the various Feed API methods (feed.publishUserAction, Facebook.showFeedDialog, and JS_API_M_FB.Connect.showFeedDialog).

Templates consist of tokens, static text, and optional template data. Tokens are wild cards that get replaced inline when a Feed story is published. Two standard tokens Facebook provides are {*actor*} or {*target*}. Facebook substitutes these tokens with the relevant users' names when the story gets published.

There are also four reserved tokens: images, flash, mp3, and video. Facebook reserves these special tokens for rendering various media types (image files, SWFs, music, and video, respectively) in a Feed story.

You can specify your own custom tokens, such as {*gift*}, {*mood*}, or {*score*}. Tokens must be wrapped in curly braces and asterisks, like this: {*TOKEN*}.

[edit] When to Include Template Data

You must include template data if any template in a template bundle includes any reserved or custom tokens; that is any tokens other than {*actor*} or {*target*}.

For example, you can have a simple template that contains just the {*actor*} and {*target*} tokens, as in:

In this case, no reserved or custom tokens are referenced, so you don't need to specify template data.

However, say you have a template that's more intricate, as in:

In this case, {*gift*} is an application-specific token which needs to be defined in the template data section. You substitute the {*gift*} token with values like "can of spam", "funny money", or "goldfish".

[edit] Constructing Template Data

Template data is stored in a JSON-encoded associative array. This array contains custom tokens you define (like {*gift*}, {*mood*}, or {*score*}) and only one of the four reserved tokens (images, flash, mp3, or video). If you include more than one kind of reserved token in the array, Facebook will choose one of these tokens, in this order:

1. images
2. flash
3. mp3
4. video

Custom and reserved tokens are arranged in key/value pairs in the array, and get substituted into the templates that are part of a template bundle. The keys of this array are the reserved and custom tokens, and their associated values are the desired substitutions. The tokens get substituted across all one line and short story sizes.

Note: {*actor*} and {*target*} should not be included in the template data array.

If you're creating templates in the Feed Template Console, you specify the template data in the Sample Template Data box. If you are publishing the Feed story through feed.publishUserAction, Facebook.showFeedDialog, or JS_API_M_FB.Connect.showFeedDialog, you specify the template data in the template_data string.

The template data may independently include an entry keyed by comments_xid.

[edit] Using the images Reserved Token

images maps to an array of up to six JSON-encoded image records. Each record must contain a src key, which maps to the image URL, and an href key, which maps to the URL where a user should be taken if she clicks the image. If possible, the images will appear in the presentation of the short version of the story.

Here's an example of an images key in an overall template_data string.

[edit] Using the flash Reserved Token

flash maps to a single record housing two required fields: swfsrc, which is the URL of the Flash object to be rendered, and imgsrc, which is the URL of an image that should be displayed in place of the Flash object until the user clicks to prompt the Flash object to play. By default, the image and the Flash object are rendered in a space that's 30px high and 100px wide. The flash record can include two additional fields called width and height, which can be used to override the default choices. The height must be an integer between 30 and 100, inclusive, and the width must one one of three numbers: 100, 110, or 130. If a height outside the [30, 100] range is provided, it is pulled into range. If a width other than 100, 110, or 130 is specified, it will be replaced with the closest of the three allowed values.

The flash record can also include two fields to specify the width and height of the Flash object once the user clicks on it. If you specify both expanded_width and expanded_height in the flash record, when the user clicks on the Flash object, it will resize to the specified size. The maximum dimensions are 320px wide and 260px high and the minimum dimensions are 30px wid and 30px high. If expanded dimensions are not specified, the dimensions of the Flash object will be the same as its thumbnail.

[edit] Using the mp3 Reserved Token

mp3 maps to a single record housing one required field: src, which is the URL of the MP3 file to be rendered within Facebook's MP3 player widget. The mp3 record can optionally include title, artist, and album fields, all of which map to strings.

[edit] Using the video Reserved Token

video maps to a single record housing two required fields: video_src, which is the URL of the video to be rendered, and preview_img, which is the URL of an image that should be displayed in place of the video until the user clicks to play. The video record can optionally include video_title, video_type, and video_link. If not provided, video_title defaults to the empty string, video_type defaults to "application/x-shockwave-flash", and video_link defaults to whatever video_src's value is.

[edit] Adding a Comment XID

comments_xid sets any comments users add to a story to a designated XID. You can then query these comments from the comment (FQL) table or render them in FBML using fb:comments.

[edit] See Also

To create template bundles, use the Feed Template Console or the API call, feed.registerTemplateBundle.

For a general overview of Feed, see Feed.