Fbml.registerCustomTags

From Facebook Developer Wiki

Jump to: navigation, search

Contents

Description

Registers custom tags you can include in your that applications' FBML markup. Custom tags consist of FBML snippets that are rendered during parse time on the containing page that references the custom tag.

Custom tags can be either private or public. For more information, see Custom Tags. When you register public custom tags, you should add the source code for the tags to the Custom Tags Directory.

To use these custom tags in an FBML snippet, you must define a namespace with the fb:fbml tag. This imports an application's custom tags into an FBML namespace. See fb:fbml for more information on how to use custom tags.

You can include <script> tags in the tag's FBML markup, and Facebook will interpret the tag as regular FBJS.

Custom tags can have attributes whose values are substituted into the tag's FBML before it's parsed. For example, a video tag can have an id attribute that indicates which video to show. Attributes can be required or optional. Optional attributes have default values that are used when the attribute is not specified.

To include attribute placeholders in a tag's FBML, use the ${attribute_name} syntax. For example, the video tag with an id attribute could have the following FBML:

<fb:swf swfsrc="http://my-video-site.tv/videos/${id}" width="425" height="344" />


This example shows how you would include this tag in an FBML snippet, and specify the ID of the video you want to show:

<fb:fbml xmlns:movies="http://external.facebook.com/apps/my_movie_app"> <movies:video id="1234" /> </fb:fbml>


In the containing page, the <videos:video id="1234" /> tag will be expanded into the following FBML:

<fb:swf swfsrc="http://my-video-site.tv/videos/1234" width="425" height="344"/>


Note: Values of inline custom tag attributes are HTML escaped before they are substituted into the custom tag's source FBML. For example,

<movies:video id="<br/>" />


is transformed into

<movies:video id="&lt;br/&gt;" />


before the tag is rendered.


Using Complex Attributes

You can also define attributes as child elements of the custom tag. These are called complex attributes. Complex attributes make it easier to assign multi-line strings to attribute values. They may contain any valid HTML character, but they may not contain any FBML tags nor most HTML tags (except for font style elements). The above example is equivalent to:

<movies:video> <music:video.id>1234</music:video.id> </movies:video>


Every custom tag has an implicit attribute called '_fb_tag_id'. The values of this attribute are guaranteed to be unique for all custom tags on a page. This attribute is useful for defining element IDs that are specific to the tag that defined them. A common use case is when making an AJAX request whose ondone handler manipulates the DOM of the custom tag (see Performance Notes below for more information).

To escape the ${attribute_name} syntax, use a preceding backslash. For example, the string '\${id}' in the tag's FBML will be rendered as '${id}' in the containing page -- it will not be substituted by the attribute value.

Important: fbml.registerCustomTags overwrites the previous definitions of any existing tags that have the same names as the new tags. This can potentially break any FBML that relies on the old definition of the tags. Use this function with extreme care, especially if other applications may be using your public tags. Be very careful when you remove attributes, and when you add new attributes, make sure you give them default values to avoid breaking existing pages that don't use the new attributes (more on tag attributes below).

Important: If your custom tags define JavaScript variables or functions or CSS classes, name them in a way that will minimize the chance for collision with other elements defined on the page. A good practice is to prefix the names of such elements with your application's name.

Note: If a tag is public, any application can fetch its source FBML by calling fbml.getCustomTags. Don't register public tags with the expectation that the source FBML won't be available to other developers.

Note: Don't use fb:ref tags with handle attributes in the source FBML for a custom tags. When the page is rendered, the handles are scoped to the application that uses the custom tag, so the handles would not be resolved properly. Instead, use fb:ref tags with url attributes.


Performance Notes

For the best possible performance for users, you should avoid including heavy JavaScript libraries or performing expensive operations such as AJAX calls in the headers and bodies of custom tags. You should only do this in footer_fbml, as this prevents long delays when the browser renders the body of the page. It will also give you the opportunity to minimize the number of AJAX calls by batching them in a single request.

For example, if you wanted to create a tag that renders a gallery of images based on an ID, you could define its fbml property as follows:

<div id="${_fb_tag_id}"/> <script> var ajax = new Ajax(); ajax.onDone = function(data) { document.getElementById('${_fb_tag_id}').setTextValue(data); }; ajax.post('http://my_app.com/ajax/gallery', {id: ${id}}); </script>


The problem with this solution is that it doesn't delay the AJAX call until the browser is done rendering the document's body. Furthermore, if the tag appear multiple times on a page, every instance will trigger a separate AJAX call, which would result in poor performance.

A better solution would be to define the tag's properties as follows:

header_fbml:

<script> var _example_app_gallery_ids = []; </script>

fbml:

<div id="${_fb_tag_id}"/> <script> _example_app_gallery_ids.push('${id}'); </script>

footer_fbml:

var idsStr = join(',', _example_app_gallery_ids); var ajax = new Ajax(); ajax.responseType = Ajax.JSON; ajax.onDone = function(data) { for (var i in data) { var id = data[i].id; var value = data[i].value; document.getElementById(id).setTextValue(value); } } ajax.post("http://my_app.com/ajax/gallery", {ids: idsStr}); </script>


For best performance, it's also recommended to include static files instead of inline CSS and FBJS. For more information, see Include files.

Parameters

RequiredNameTypeDescription
required tags array a JSON-encoded list of tag objects. Each tag object is an object with the following properties:
  • name (required) (string): the name of the tag. The name must be a string up to 30 characters. Only letters, numbers, underscores ('_') and hyphens ('-') are allowed.
  • type (optional) (string): Specify either leaf or container. Leaf tags can't contain any other tags (similar to <fb:name/>). Container tags may contain children between their open and close tags (like <fb:editor></fb:editor>). (Default value is leaf.).
  • description (optional) (string): A full description of the tag's functionality. This is used for documentation only, and is especially useful for public tags.
  • is_public (optional) (string): Specify either true or false. Specifying true indicates that other applications can use this tag. You can have a mix of public and private tags within the same array. (Default value is false.).
  • attributes (optional) (mixed): A list of attribute objects. Attributes are used to add dynamic elements to tags. The values of those attributes are substituted into the tag's FBML before it's parsed. Each attribute has the following fields:
    • name (required) (string): The attribute's name. The name must be a string up to 30 characters in length. Only letters, numbers, underscores ('_') and hyphens ('-') are allowed.
    • description (optional) (string): The attribute's description. This is used for documentation only, and is especially useful for public tags.
    • default_value (optional) (string): The value to use when the attribute is missing. If an attribute doesn't have a default value, it is considered to be required and the developer will see an error message if the attribute is missing.
  • fbml (required) (string): The FBML markup to substitute into the page where the tag is encountered. This property is required only for leaf tags.
  • open_tag_fbml (required) (string): The FBML markup to substitute into the page where the open tag appears. This property is required for container tags only.
  • close_tag_fbml (required) (string): The FBML markup to substitute into the page where the close tag appears. This property is required for container tags only. Note: Facebook recommends you do not include <script> tags in this FBML snippet.
  • header_fbml: An FBML snippet that is rendered once on the page before the first tag that defined it. If multiple tags define the same value for header_fbml, and more than one of them appear on a page, then header_fbml is rendered only once. You should only use this for including CSS and initializing any JavaScript variables, not for rendering visible content. Facebook recommends you avoid including heavy JavaScript libraries and performing expensive JavaScript operations in header_fbml for performance reasons. Instead, use footer_fbml.
  • footer_fbml: Similar to header_fbml, it's an FBML snippet that gets rendered after all custom tags are rendered. Facebook recommends you include heavy JavaScript libraries and perform any expensive JavaScript operations in footer_fbml, and avoid them in fbml, open_tag_fbml, close_tag_fbml, and header_fbml.

Example Requests

[{name: 'video', type: 'leaf' description: 'Renders a fb:swf tag that shows a video from my-video-site.tv. The video is 425 pixels wide and 344 pixels tall.', attributes: [{name: 'id', description: 'the id of the video', default_value: '1234'}], fbml: '<div class="my_videos_element"><fb:swf swfsrc="http://my-video-site.tv/videos/${id}" width="425" height="344"/></div>'}, header_fbml: '<style>div.my_videos_element { border: black solid 1px; padding: 5px;}</style>' {name: 'gallery', type: 'container' description: 'Renders a standard header and footer around one or more "video" tags. The header contains the gallery\'s title, which the user can specify', attributes: [{name: 'title', description: 'the title of the gallery'}], open_tag_fbml: '<div class="my_videos_element"><div class="video_gallery_title">${title}</div><div class="my_videos_gallery">', close_tag_fbml: '</div></div>', header_fbml: '<style>div.my_videos_element { border: black solid 1px; padding: 5px;}</style>'} ]

See Also

Retrieved from "http://wiki.developers.facebook.com/index.php/Fbml.registerCustomTags"
reference