Writing Facebook Markup Language (FBML) ! Complete information on it


Writing Facebook Markup Language (FBML) 

In This Chapter Exploring the FBML markup language Determining the HTML elements you can use Working with users and groups Displaying content based on a user’s permissions Adding Facebook UI elements and widgets Creating requests and invitation forms Although the Facebook API (see Chapter 3) is primarily used for retrieving Facebook data, Facebook Markup Language (FBML) is the tool that allows you to fully embed your app within the Facebook environment. FBML allows you to render content onto the Facebook canvas, conditionally display info to different users depending on their permissions, and tap into several Facebook staples, such as Wall, Board, and profile box. In short, FBML is the developer’s primary tool for building applications that deeply integrate into the Facebook Platform. In this chapter, I walk you through using FBML productively as you develop your Facebook application. Exploring FBML FBML is a combination of Facebook-specific elements (tags) and a subset of HTML elements that are appropriate for use in the Facebook environment. When the Facebook server processes FBML (which can be sent as a parameter from many of the Facebook API calls), it processes the markup and displays the output in HTML for rendering in a browser. 09_277959-ch04.qxp 5/5/08 11:26 AM Page 95 You can divide FBML into six main types of elements: Facebook field placeholders: Several elements are used as placeholders to display Facebook-related data. For example, the fb:name tag is used to output the name of the specified user: Conditional programming elements: FBML contains several elements used for adding conditional logic to your code. Consider, for example, the fb:if-can-see element. It allows you to tailor the content based on the permission level of the logged-in user. Here’s how you could display different content depending on the user’s ability to see another user’s Wall: Would you like to write on the Wall?
What do you want to do?
Presentation elements: A third group of elements is used for presenting text and media content. The fb:photo element, for example, displays a Facebook photo based on its photo ID: Facebook widgets: A fourth group of elements is used to insert a familiar Facebook UI element, such as a Wall, a Board, or the Dashboard. Using these elements, you can take advantage of these Facebook UI elements without having to code and format them yourself. For instance, if you want to display a Wall in your app, you could use the fb:wall element: Congrats on your prom queen award. General markup elements: The fifth group of tags exposes a wide variety of general functionality in the Facebook Platform that is needed for developing robust applications. The fb:error tag, for example, is used to display a Facebook error message: Application Error Something weird just happened to our app. We have no idea how this happened.
96 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 96 HTML subset of elements: Lest we forget HTML, FBML also includes a subset of HTML elements that you can work with inside of the environment. As Table 4-1 shows, you can work with the vast majority of bodylevel elements. However, because you are working within the Facebook environment, the top- and head-level elements are not available. Table 4-1 Supported and Unsupported HTML Elements Group Supported Elements Unsupported Elements Block-level address, blockquote, noscript elements center, del, div, h1, h2, h3, h4, h5, h6, hr, ins, p, pre List elements dl, dt, dd, li, ol, ul dir, menu Table elements table, caption, tbody, td, colgroup, col tfoot, th, thead, tr Form elements form, fieldset, legend, button input, label, optgroup, option, select, textarea Special inline a, bdo, br, font, img, q, span, applet, basefont, elements script, style, sub, sup iframe, map, area, object, param Phrase elements abbr, acronym, cite, code, dfn, em, kbd, samp, strong, var Text style b, big, i, s, small, strike, tt, u Top-level, head, html, head, body, and and frame frameset, base, elements isindex, link, meta, style, title Table 4-2 provides a listing of all the FBML elements, organized by their group. Table 4-2 FBML Tags Groups FBML Elements Description Users and groups fb:name Outputs the name of the specified user fb:grouplink Outputs the name of the specified group (continued) Chapter 4: Writing Facebook Markup Language (FBML) 97 09_277959-ch04.qxp 5/5/08 11:26 AM Page 97 Table 4-2 (continued) Groups FBML Elements Description fb:user Specifies that the contained content is owned by the specified user fb:pronoun Outputs a pronoun for the specified user fb:profile- Displays the specified user’s profile pic picture Conditional fb:is-in- Displays content if the user is content displays network inside a specified network fb:if-can-see Displays the contained content if the current user passes a privacy check for a specific condition fb:if-can- Displays enclosed content only if the see-photo current user has permission to see the specified photo fb:if-is- Displays contained content only if the app-user specified user has accepted the terms of service of the application fb:if-is- Displays the contained content only if friends- the specified user is friends with the with-viewer current user fb:if-is- Displays the contained content only if group-member the specified user is a member of the specified group fb:if-is-user Displays contained content only if the current user is one of the specified users fb:if-user- Displays the contained content only has-added-app if the specified user has added the app to his or her profile fb:if Displays content if the condition evaluates to true fb:else Takes care of the else case inside any of the fb:if* or fb:is-in-network tags fb:switch Evaluates every contained FBML tag and outputs the first one that evaluates to a nonblank string 98 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 98 Groups FBML Elements Description fb:default Used inside of an fb:switch element, it outputs content if all other FBML tags before it are blank Profiles fb:wide Displays contained content only when profile box is in the wide column of the user’s profile fb:narrow Displays contained content only when profile box is in the narrow column of the user’s profile fb:profile- Displays a link on the user’s profile action underneath his or her photo fb:user-table Displays a user table displaying the name and thumbnail picture of the user. This tag only works in a profile box. fb:user-item Specifies a user to be displayed inside of a fb:user-table fb:subtitle Specifies the subtitle for the profile box fb:action Displays an action link on the right side of a profile box or Dashboard Media fb:iframe Adds an iframe element to the page fb:photo Displays a Facebook photo fb:mp3 Displays a Flash audio player fb:swf Displays a Shockwave Flash object fb:flv Displays a Flash FLV player for video/audio streaming fb:silverlight Displays a Microsoft Silverlight control Status messages fb:error Displays a standard error message fb:explanation Outputs a standard explanation message fb:success Displays a standard success message fb:message Displays the heading for a message (used inside an error, explanation, or success message) (continued) Chapter 4: Writing Facebook Markup Language (FBML) 99 09_277959-ch04.qxp 5/5/08 11:26 AM Page 99 Table 4-2 (continued) Groups FBML Elements Description Dialog boxes fb:dialog Displays a standard pop-up dialog box fb:dialog- Displays the title to the dialog box title fb:dialog- FBML contents of the dialog box content fb:dialog- Displays a button in the dialog box button Editor displays fb:editor Creates a two-column form fb:editor- Outputs a Submit button inside an button editor form fb:editor- Container for editor buttons buttonset fb:editor- Outputs a cancel button inside an cancel editor form fb:editor- Enables you to display any valid FBML custom content in the editor form fb:editor-date Creates a date selector fb:editor- Displays a horizontal line spacer divider fb:editor- Displays a month selector month fb:editor- Outputs a text box for an editor form text fb:editor- Displays a text area for an editor form textarea fb:editor- Displays a time selector time Request forms fb:request- Defines a request form form fb:multi- Renders a tabular display of friends in friend-input a request form (or, if condensed= ”true”, displays a condensed list) fb:request- Displays a Submit button for form-submit condensed request forms 100 Part II: Poking the API 




09_277959-ch04.qxp 5/5/08 11:26 AM Page 100 Groups FBML Elements Description fb:req-choice Defines a button at the bottom of a user’s request page Page navigation fb:dashboard Renders a top Dashboard fb:action Displays an action link in a Dashboard fb:create- Adds a Create button to the Dashboard button fb:help Adds a Help link to the Dashboard fb:header Displays a Facebook title header fb:mediaheader Displays a media-oriented header fb:header- Provides a title for a media header title fb:owner- Specifies an action link inside a media action header fb:tabs Defines a tab set for page navigation fb:tab-item Defines a tab link Facebook widgets fb:wall Renders a Wall on the page and UI elements fb:wallpost Displays a post on a Wall fb:wallpost- Outputs an action link at the bottom of action a wallpost fb:board Renders a discussion board (Facebook handles all the board duties) fb:comments Renders a Wall for comments (Facebook handles all the Wall duties) fb:friend- Displays a box for selecting friends selector fb:typeahead- Displays a customized type-ahead box input fb:typeahead- Specifies custom settings for the option type-ahead input box (continued) Chapter 4: Writing Facebook Markup Language (FBML) 101 09_277959-ch04.qxp 5/5/08 11:26 AM Page 101 Table 4-2 (continued) Groups FBML Elements Description fb:random Picks an item inside the tag based on weights specified in the fb:random-option items fb:random- Displays content to be rendered when option selected in an fb:random tag fb:share- Outputs a standard Share button button fb:submit Transforms an image or text link into a Submit button Attachments fb:attachment- Displays a link in a Wall or message preview attachment that inserts new content when clicked Miscellaneous fb:fbml Specifies that the FBML code it contains is specific to a particular version of FBML fb:fbmlversion Outputs the current version of FBML (for debugging use only) fb:title Sets the page title or, when contained by fb:comments or fb:board, sets the title for these widgets fb:js-string Renders a block of FBML into an FBML block JavaScript variable fb:redirect Redirects to the specified URL inside the Facebook canvas page fb:ref Outputs FBML content from a given source fb:time Outputs the date/time based on the current user’s time zone fb:page-admin- Adds a standard edit header for quick edit-header access to a page’s app configuration (only for apps that can be added to Facebook pages) fb:user-agent Displays contained content to a specific user-agent (browser) 102 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 102 Groups FBML Elements Description fb:google- Adds Google Analytics code to page analytics fb:mobile Displays the contained content only when accessed from the Facebook mobile Web site Working with Users and Groups FBML has several tags that enable you to output information about a user. Perhaps the most basic is the fb:name element, which displays the name of the user based on the criteria supplied in the attributes. For example, to render a person’s Facebook name, I supply the user ID through the uid parameter: My friend’s name is Facebook renders the text as shown in Figure 4-1. The name is displayed and hyperlinked to the profile page of the user. If you want to display the name of the logged-in user, a variety of options are available to do so, such as the following: You can specify the reserved phrase loggedinuser as the value for the uid. You can supply the user ID from a variable. For example, in PHP, I could write the following (where $user is the variable for the logged in user): echo “” You could hardcode the ID value: Figure 4-1: Displaying a name using fb:name. Chapter 4: Writing Facebook Markup Language (FBML) 103 09_277959-ch04.qxp 5/5/08 11:26 AM Page 103 However, the uid parameter alone is usually not enough when dealing with the current user. You need to specify exactly how you want to refer to the person. By default, Facebook refers to the current user as you when it renders a name. Therefore, the following code Hello would display as Hello you If you would like to display a user’s actual name instead of you, add useyou as an attribute: Hello This tag displays the following when I am the current user: Hello Rich Wagner The fb:name tag has several additional attributes (see Table 4-3) that enable you to specify how a user’s name is presented. Table 4-3 fb:name Attributes Attribute Description uid Specifies the desired user ID (or page ID) (can also use loggedinuser or profileowner). (Required) firstnameonly Displays the first name of the user only. (Defaults to false) linked Specifies whether to link the user’s name to his or her profile. (Defaults to true) lastnameonly Displays the last name of the user only. (Defaults to false) possessive Displays the name as possessive (usually adding ‘s). (Defaults to false) reflexive Output yourself if the useyou attribute is true. (Defaults to false) shownetwork Displays the primary network of user. (Defaults to false) 104 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 104 Attribute Description useyou Replaces user name with you if uid is the current logged-in user. (Defaults to true) ifcantsee Outputs alternate text if the current user cannot access the user specified in uid. capitalize Capitalizes the text if useyou is true and uid is the current user. subjected Specifies the ID of the subject in a sentence where this name is the object of the verb. Reflexive is used when it makes sense. Here are some common ways to use the fb:name attributes: To display the first name only, use firstnameonly: Hello To display the last name only, use lastnameonly: Hello To capitalize the name if useyou=”true” and uid=”loggedinuser” are set, use capitalize=”true”: is capitalized. To make the name possessive, use possessive=”true”: calendar is ready for viewing. This displays as Rich’s calendar is ready for viewing. If you don’t want to link the user’s name to his or her profile, set the linked attribute accordingly: It does not make sense to link to profile. In addition to fb:name, you can also use the fb:pronoun tag to output the appropriate pronoun for a particular user. Table 4-4 lists the various attributes. Chapter 4: Writing Facebook Markup Language (FBML) 105 09_277959-ch04.qxp 5/5/08 11:26 AM Page 105 Table 4-4 fb:pronoun Attributes Attribute Description uid User ID. (Required) useyou Use “you” if current user is the iud. Default is true. possessive Use his, her, your, or their. Default is false. reflexive Use himself, herself, yourself, or themselves. Default is false. objective Use him, her, you, or them. Default is false. usethey Use “they” if no gender is specified. Default is true. capitalize Capitalize the pronoun. Default is false. To display the profile picture of a user (or Facebook page), you can use the fb:profile-pic element. Its size attribute enables you to specify one of four image sizes: thumb (50px wide), small (100px wide), normal (200px wide), or square (50wx50h). Consider the following code using both fb: pronoun and fb:profile-pic: recently updated profile picture to:
Displaying Content Conditionally One of the key building blocks of Facebook is the ability of a user to specify who gets to see his or her information and content. Typically, friends get to see most everything, a few friends get to see a limited profile, and the public gets to see basic friends lists. Therefore, as application developers for the Facebook Platform, you have to be aware of the visibility of any user data you want to display. FBML provides several elements that enable you to display content conditionally — depending on the view of the current user. However, the context in which you can use these tags is very specific. The elements starting with fb:if, for example, are available on a canvas page, but not in a profile box. The fb:visible elements are designed for testing inside the profile box only (see Chapter 1 for more on the canvas pages and profile boxes). 106 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 106 Testing on canvas pages The following elements are available on a Facebook canvas page, but not in a profile box: fb:if-can-see fb:if-can-see-photo fb:if-is-app-user fb:if-is-friends-with-viewer fb:if-is-group-member fb:if-is-user fb:if-user-has-added-app fb:is-in-network Each of these works like an if statement that you are probably used to in another programming language. If the tag evaluates to true, the content contained inside of it is displayed. Each of these also supports the use of the fb:else tag to display content when the tag evaluates to false. Testing with fb:if-can-see The fb:if-can-see tag displays the content it contains depending whether the current user has privileges to see the area specified by its what parameter. For example, the following code tests to see whether the current user can see the profile for user 685578792: is excited to hear from you. is unavailable for comment. Because I am friends with this user, when I am signed in, I get the following output: Jared Wagner is excited to hear from you. However, for nonfriends, the fb:else content is displayed: Jared Wagner is unavailable for comment. The what attribute can be any of the following values: search (default), profile, friends, not_limited, online, statusupdates, wall, groups, courses, photosofme, notes, feed, contact, email, aim, cell, phone, mailbox, address, basic, education, professional, personal, and seasonal. Chapter 4: Writing Facebook Markup Language (FBML) 107 09_277959-ch04.qxp 5/5/08 11:26 AM Page 107 Displaying photos with fb:if-can-see-photo Similarly, the fb:if-can-see-photo tag is used when you are trying to determine whether you can display a photo using fb:photo, which can be used to reference any photo on Facebook. For example: recently snapped the following picture:
The pid attribute specifies the ID of the photo you can check on. The pid is something you can obtain using the photos.get API method. Alternatively, you can specify a pid that you obtain from a Facebook photo URL if you also supply the optional uid attribute. For example, suppose I have a photo I want to render that is at the following URL: http://www.facebook.com/photo.php?pid=570575&id=530377451&ref=nf By identifying the pid and uid values from the URL, I can use them in my FBML call: recently snapped the following picture:
Who said a picture is worth a 1,000 words? I am sure it wasn’t that good of picture anyway.
Notice that fb:else can be used with fb:if-can-see-photo, as well as with any of the other conditional FBML tags. Testing for app users You can use the fb:if-is-app-user and fb:if-user-has-added-app elements when you want to conditionally display content based on whether the specified user (not necessarily the current user) is a user of your app. These two elements are quite similar, but the difference is as follows: fb:if-is-app-user displays content if the specified user has accepted the terms of service of the application. fb:if-user-has-added-app outputs contained content if the specified user has added the app to his or her account. For example: 108 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 108 The user you requested is already a user of DétenteFussion.
Would you like to send an invitation to now to sign up for DétenteFussion?
Checking for specific users You may want to display content only when the specified user is friends with the currently logged-in user. To do so, use fb:if-is-friends-withviewer. Here’s a sample: You are already friends with
Would you like to send a request to become your friend?
The fb:if-is-friends-with-viewer has an optional includeself attribute to return true if the viewer is the same as the uid. You can also display content conditionally using fb:if-is-user only if the user shows up in a comma-separated list of user IDs. If the ID of the current user is inside the list, content is displayed. Otherwise, the user is out of luck. Here’s a sample: Hey, you are among the finalists to receive a free iPod Nano.
Better luck next time!
Finally, you can also perform a couple more conditional checks using fb:isin-network (if user is in the specified network) and fb:if-is-groupmember (if user is in the specified group). Showing and hiding content in profile boxes Because of the potential for abuse, the fb:if* elements are no longer allowed to be used within profile boxes starting with FBML 1.1. Instead, you can use the following fb:visible-to* tags: fb:visible-to-owner fb:visible-to-user Chapter 4: Writing Facebook Markup Language (FBML) 109 09_277959-ch04.qxp 5/5/08 11:26 AM Page 109 fb:visible-to-friends fb:visible-to-app-users fb:visible-to-added-app-users fb:visible-to-connection These tags enable you to customize the content of the profile box depending on the viewer. However, while the fb:if* tags preprocess the content that is output based on the conditional logic, these fb:visible-to* elements simply show or hide already-processed content depending on the viewer. For example, the following FBML code displays various content in the profile box depending on the user: Hello , this is your very own box.
Hello Jordan. You alone get to see this message.
Hello friends of . If your friend liked this app, we bet you will too!
Awesome dude- you use this app like does.
Super! You already have this added to your profile. You are cool too!
For Facebook pages, this content is only displayed if use is a fan of the Facebook page.
HERE; $facebook->api_client->profile_setFBML($profileOnlyContent); ?> The fb:visible-to-user tag renders for the owner. Therefore, all of the text rendered by the code shown above will be visible to the owner. 110 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 110 When using any of the fb:visible-to* elements, be sure not to display private or personal information inside the content. Although the content inside the blocks is not visible to the people outside the intended viewer, it is actually still in the page’s source code. Therefore, if your diet-monitoring app contained the following code: Congrats. You have lost another pound. You are now just 184 pounds.
anyone coming to the user’s profile who viewed the page source code could see this rather sensitive info. Each of these tags contains a bgcolor attribute that enables you to specify the color of the profile box if the user is not allowed to see the visible content. Therefore, in the following snippet, the content is visible to the profile owner, but everyone else sees a gray box: Hello , this is your very own box.
See Chapter 10 for more details on working with the profile box. Using fb:if and fb:switch The fb:if-* elements (described in the previous section) use conditional logic to display content based on the permissions of the current user. You can also use two additional FBML tags to control the output of your application: fb:if fb:switch The fb:if tag displays the content if the value attribute evaluates to true. You can use it in conjunction with fb:else to create a typical if...else conditional block. Here’s an example from PHP: $page_id = 6829493713; $check = $facebook->api_client->pages_isAdmin($page_id); echo “Would you like to edit the page?”; echo “Not Authorized!”; echo “” Chapter 4: Writing Facebook Markup Language (FBML) 111 09_277959-ch04.qxp 5/5/08 11:26 AM Page 111 The fb:switch element evaluates each of the FBML tags inside of it and renders the first one that evaluates to a non-empty string. You can use the fb: default tag to display content if no other tags are rendered. Note that I use the fb:swf element to render a Shockwave/Flash object in my page: This is the first thing that evaluates to a non-empty string...
Well, at least you have this nice text to look at.
Adding Facebook UI Elements and Widgets One of the most powerful aspects of FBML is that it allows you to instantly add Facebook core UI elements and “widgets” into your application with just a few lines of markup code. The benefits are twofold: It eliminates the need for you to reinvent the wheel and write your own custom solution. It enables your application to easily take on the look and feel of Facebook itself. You can add several core UI elements to your canvas page, including the following: Dashboard page header (fb:dashboard) Dashboard navigational link (fb:action) Dashboard Create button (fb:create-button) Dashboard help link (fb:help) Title header (fb:header) Media header (fb:mediaheader) Navigation tabs (fb:tabs, fb:tab-item) These core elements are used as basic interface building blocks for constructing the navigation of most any application. I discuss how to work with these FBML tags in Chapter 8. 112 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 112 You also find several general-purpose Facebook widgets with built-in functionality that you can drop onto your canvas page, including the following: Discussion board (fb:board) Comments Wall (fb:comments) Do-it-yourself Wall “constructor kit” (fb:wall, fb:wallpost, fb: wallpost-action) Friend selector box (fb:friend-selector) Type-ahead text box (fb:typeahead-input, fb:typeaheadoption) The following sections discuss these tags in further detail. Discussing it on the board To add a discussion board to your app, use the fb:board element and customize its setting through the attributes: Discuss this Dummies app The xid is the only required parameter. Each board you create should have a unique ID. The ID can only contain alphanumeric characters, underscores, and hyphens. The canpost, candelete, canmark (as relevant or irrelevant), and cancreatetopic attributes all enable you to specify how much users can do on the discussion board. The numtopics parameter determines the number of topics to display on a page. The returnurl determines what URL should be displayed when a back link is clicked (default is the current page). You can use the fb:title tag inside of an fb:board (or fb:comments) to set the title for the board. The results are displayed in Figure 4-2. Figure 4-2: fb:board creates a discussion board. Chapter 4: Writing Facebook Markup Language (FBML) 113 09_277959-ch04.qxp 5/5/08 11:26 AM Page 113 Content can now be added to your board without writing any additional code. When a user adds content or browses through it (see Figure 4-3), the user leaves the canvas page of your application and goes to a page devoted to the board. The user can click the Back link to return to your application (see Figure 4-4). Although you don’t have full access to the data of these widgets, Facebook handles all the application and data-management responsibilities for you. Another comment on the Wall The fb:comments tag is used to create a fully functional Wall in much the same way as fb:board creates a discussion board. It has many of the same attributes as fb:board as well. Here’s a sample: Write on the Dummies Wall The returnurl provides the URL to return to when the user clicks the Back link. Also, notice the showform attribute. When set to true, the entry form is displayed inside your page. If false, the user needs to click the Write Something link (see Figure 4-5) to add text. Figure 4-4: Returning to the app after the board. Figure 4-3: User leaves app page to enter the board. 114 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 114 Building a Wall post by post Although the fb:comments element allows you to add a Wall to your page, Facebook handles all the post-entry and other interaction with users through its Wall interface. However, at some point, you may want to have greater control over your Wall and construct the entries yourself. To do so, you can use the fb:wall, fb:wallpost, and fb:wallpost-action elements. The fb:wall element serves as the Wall container; fb:wallpost, which should be placed inside an fb:wall, outputs a Wall post. Placed inside an fb:wallpost, the fb:wallpost-action tag places an action link at the end of the post. Note that, unlike fb:comments, the fb:title element does not work with fb:wall. The following code renders a Wall with three posts:

Facebook Wall For Dummies

Glad you could come today! Reply to Great app. I am telling all my friends. Reply to Cool! Reply to Figure 4-6 shows how this Wall is displayed. Figure 4-5: Dropping a Wall onto your page is as easy as using an fb: comments tag. Chapter 4: Writing Facebook Markup Language (FBML) 115 09_277959-ch04.qxp 5/5/08 11:26 AM Page 115 Creating Requests and Invitations The fb:request-form tag is used to display the ubiquitous Facebook request form for sending requests to the friends that the current user specifies. Most everything is packaged up from a UI standpoint, freeing you from re-creating the form and its controls. Note that users can only invite a total of 20 users per day for a given application using fb:request-form. Building a standard-sized request form The typical scenario is to use an fb:request-form in conjunction with the fb:multi-friend-selector, which displays a tabular arrangement of users for users to select from. Consider the following code: Both the type and content attributes are required. The type attribute contains the type of request you are generating, while content is used to define the contents of the request itself. The content value is FBML code that contains plain text, links, or the fb:req-choice tag. The fb:req-choice element is used to define a button at the bottom of a request on the user’s Requests page. It contains two attributes: label (the display text on the button) and url (an absolute URL that the user will be taken to). When you are working with this attribute value, be sure to encode it. For example, in PHP, you would use the htmlentities function: Figure 4-6: Create your own Wall with fb:wall. 116 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 116 content=”Please join today. Don’t delay, sign up today.”); ?>”> Getting back to the fb:request-form, the invite attribute specifies whether the message is an invitation or a request. The action attribute determines the location that the user goes to when he or she is done with the process or has clicked the Skip This Step button. As I mentioned already, fb:multi-friend-selector displays an arranged table of users and profile pictures that the user uses to select the friends for the request. It has several attributes of note: actiontext displays the instructional caption at the top of the control. (Required) showborder draws a border around the outside of the control. rows indicates the number of rows to display at once. (Default is 5.) max specifies the maximum number of users that can be selected. exclude_ids is an array of user IDs to exclude from the user list. bypass specifies the type of the Bypass button — step (Skip This Step), cancel (Cancel), or skip (Skip). (Default is skip.) The POST variables that are returned are an array of user IDs that the user selected. Consider an example of an application invite. The first step is to gather a list of friends of the current user and then compile these lists of user IDs into an exclusion list. (You never want to send an invitation to someone who already has the app installed!) I use the friends.getAppUsers API method for this task: $app_users=$facebook->api_client->friends_getAppUsers(); if ($app_users) { for ($i=0;$i selfishly wants you to add F8 For Dummies! so that can get credit for it. FBML; Finally, these variables are then inserted into the fb:request-form and fb:multi-friend-selector tags: ”> ” /> Here’s the full source code for the example: api_client->friends_getAppUsers(); if ($app_users) { for ($i=0;$i selfishly wants you to add F8 For Dummies! so that can get credit for it. 118 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 118 FBML; ?> ”> ” /> Figure 4-7 shows the request form, while Figure 4-8 displays the request message to be sent to the selected users. Figure 4-7: Building a request form is a snap with fb: requestform. Chapter 4: Writing Facebook Markup Language (FBML) 119 09_277959-ch04.qxp 5/5/08 11:26 AM Page 119 Building a condensed request form You can also use a condensed version (see Figure 4-9) of the fb:multifriend-selector tag by adding a condensed=”true” attribute value to the fb:multi-friend-selector tag. If you use this option, I recommend specifying the width by adding a style attribute. For example: ”> ” /> Figure 4-9: Displaying a smaller version of the request form. Figure 4-8: Displaying the request message. 120 Part II: Poking the API 09_277959-ch04.qxp 5/5/08 11:26 AM Page 120 Chapter 5 E

No comments