“Goin’ API” with Facebook Developer Tools Complete information on it !

“Goin’ API” with Facebook Developer Tools 

In This Chapter Introducing Facebook developer tools Working with the Facebook dAPI Console Experimenting with the FBML Test Console Crafting stories in the Feed Preview Console Tracking down FBJS bugs with Firebug Ask an experienced carpenter about a set of tools he recommends, and chances are good that you will get a passionate, opinionated response. After all, he spends hundreds of hours a year working with his tools; they become an extension of who he is as a professional craftsman. He doesn’t want to simply use just any set of tools. In the same way, experienced Web developers have an editor and a set of development tools that they are every bit as passionate about as the carpenter is of his table saw. These software tools enable the developer to get the job done quickly, efficiently, and with fewer bugs. Facebook had this thought in mind when it came to the release of the Facebook Platform — providing not just the extensions developers need, but also the testing tools they need to make their apps work. You can use these tools to quickly discover and test API functionality outside of an application. The suite includes the following tools: API Test Console: Use to make test calls to the Facebook API outside of your app. FBML Test Console: Use to test out FBML markup code. Feed Preview Console: Use the Feed Preview to see exactly how the feed story looks prior to actually sending it out. 12_277959-ch07.qxp 5/5/08 11:27 AM Page 167 Additionally, Firebug, a third-party script debugger (available at www.get firebug.com), is used for debugging Facebook JavaScript (FBJS). The following sections discuss all of these in greater detail. Working with the API Test Console The API Test Console (see Figure 7-1) is used to interact with the main Facebook programming interface. You can use it to call any of the available methods. To display this console, go to http://developers.facebook. com/tools.php?api. The input boxes are provided on the left side of the page, and the raw results of the call are provided in the box on the right. Here are the main inputs: The User ID field displays the user ID of the currently logged-in user (you). This is a read-only field. The Application drop-down box displays a list of your applications and the Test Console. The results of the call are always displayed in the right-side box, regardless of the Application value. However, this box is useful when you are testing application-specific methods (such as users.isAppAdded). The Response Format drop-down list enables you to toggle among the three output formats: XML, JSON, and Facebook PHP Client. Figure 7-1: The API Test Console. 168 Part II: Poking the API 12_277959-ch07.qxp 5/5/08 11:27 AM Page 168 The Callback field enables you to specify a JSONP callback function. (JSONP allows you to define a function in your application to handle the results of the Facebook API call.) The Method drop-down box lists each of the methods available. The User ID, Application, Response Format, Callback, and Method boxes are displayed for every method. If the method has additional parameters, they are displayed below the Method drop-down list box. For example, although the friends.get method (see Figure 7-1) needs no additional parameters, pages.getInfo provides input for four (see Figure 7-2). Using the API Test Console, suppose you want to check and see whether two users are friends. To do so, you can select friends.areFriends from the Method drop-down box. The uid1 and uid2 parameter boxes are displayed below the Method. Enter two user IDs in these boxes and click the Call Method button. The XML results are displayed in the output box, as shown in Figure 7-3. You can switch the Response Format value to display the result in JSON or Facebook PHP Client. See Chapter 3 for full details on how to work with the Facebook API. Figure 7-2: Parameter values are specified using the input

boxes. Chapter 7: “Goin’ API” with Facebook Developer Tools 169 12_277959-ch07.qxp 5/5/08 11:27 AM Page 169 FBML Test Console The FBML Test Console is a utility that you can use to enter Facebook Markup Language (FBML) markup code in a code box and then instantly see the results displayed in a preview box along with the HTML code that is generated. Perhaps most significant is that the console allows you to render results in any of the possible output contexts, including the following: Profile box (wide or narrow) Canvas E-mail Notification Request Feed (title or body) Mobile device To display the FBML Test Console, go to http://developers.facebook. com/tools.php?fbml. Figure 7-4 shows the console. Figure 7-3: Displaying the results of a method call in the API Test Console. 170 Part II: Poking the API 12_277959-ch07.qxp 5/5/08 11:27 AM Page 170 Several input controls are available: The User field displays your user ID. This entry is read-only. The Profile field displays the profile content in which the FBML code will be rendered. By default, the current user ID is displayed. However, you can adjust this value. The Position field allows you to specify the output of your code: wide (profile box), narrow (profile box), canvas, e-mail, notification, request, feed title, feed body, or mobile. The API Key field is used to display an application API key. By default, it displays the API key for the Test Console. However, you can add the API key of your application. The box below the API Key field is used to enter FBML markup code. After you have entered information in these spaces, click the Preview button to render the results. Figure 7-5 displays the output of a wide profile box. Using the FBML Test Console helps you identify potential problems in your code before you put it into your application. For example, Figure 7-6 displays FBML markup code that produces an error when you try to render in a profile box. Figure 7-4: The FBML Test Console is the official play area for FBML coders. Chapter 7: “Goin’ API” with Facebook Developer Tools 171 12_277959-ch07.qxp 5/5/08 11:27 AM Page 171 However, running the same code on a canvas page works fine, as shown in Figure 7-7. Figure 7-6: fb:if-* tags are not allowed in profile boxes. Figure 7-5: Testing the FBML code. 172 Part II: Poking the API 12_277959-ch07.qxp 5/5/08 11:27 AM Page 172 See Chapter 4 for full details on how to use FBML. Feed Preview Console Stories published using the feed.publishTemplatizedAction method are an important part of any application to test thoroughly before you go live, because you communicate with dozens or maybe even thousands of people in the process. The Feed Preview Console allows you to experiment and preview a Mini-Feed story as well as the News Feed story that appears in the friends of the user. Go to http://developers.facebook.com/tools.php?feed to display the Feed Preview Console, as shown in Figure 7-8. Figure 7-7: But fb:if-* tags work fine when rendered on canvas pages. Chapter 7: “Goin’ API” with Facebook Developer Tools 173 12_277959-ch07.qxp 5/5/08 11:27 AM Page 173 Several input fields are available, and most correspond to the parameters of feed.publishTemplatizedAction, as follows: The Application drop-down box displays the active application — either the Test Console or one of your applications. The Actor_id field allows you to select the user or page in which you would like to publish the Mini-Feed story. The Target_ids field is used to enter one or more user IDs that are directly linked to the story. (Normally optional, but required if you use {target} in the Title_template or Body_template field). The Title_template field contains the FBML markup that is used as the title for the story. The {actor} token must be included in this markup. Optionally, you can also add your own tokens and then associate values using the Title_data parameter (see the next bullet). This parameter is required. The Title_data field is used to display a JSON associative array (grouped in token:substitution pairs) that you want to have substituted into the Title_template field. (The array cannot substitute for {actor} and {target}.) Figure 7-8: The Feed Preview Console. 174 Part II: Poking the API 12_277959-ch07.qxp 5/5/08 11:27 AM Page 174 The Body_template field contains the FBML markup for the story’s body. The Body_data field, much like the Title_data field, contains a JSON associative array of values that you want to substitute into the Body_template field. The Body_general field provides additional markup to be displayed in the story’s body. The Page_id field is used to specify a page ID when publishing to a Facebook page that has the app installed. The Image_x and Image_x_link fields provide a way to enter up to four images or image links. After the story has been composed in these various fields, you can click the Call feed.publishTemplatizedAction button to preview both the News Feed and Mini-Feed stories in the Preview window. Figure 7-9 shows an example. See Chapter 11 for more details on how to work with the feed.publishTemplatizedAction API call. Figure 7-9: Previewing stories in the Feed Preview Console. Chapter 7: “Goin’ API” with Facebook Developer Tools 175 12_277959-ch07.qxp 5/5/08 11:27 AM Page 175 Debugging FBJS with Firebug Although Facebook does not have an integrated testing console for FBJS, you can debug your FBJS code using Firebug, the popular JavaScript debugger that integrates with your Firefox browser. However, unlike the other experimental consoles, you need to work with your application files on your server. Before continuing, go to www.getfirebug.com and download a free copy of Firebug. You must be using Firefox to download and install it. After you have installed Firebug, you can activate it from the Firebox Tools menu (choose Tools➪Firebug➪Open Firebug). When you open your application, you can then debug the FBJS code by clicking Firebug’s Script tab. You can set breakpoints and watch variables as you refine your Facebook JavaScript code. See Figure 7-10. Figure 7-10: Firebug debugger tracks down FBJS bugs. 176 Part II: Poking the API 12_277959-ch07.qxp 5/5/08 11:27 AM Page 176 Part III Developing Facebook Applications 13_277959-pp03.qxp 5/5/08 11:27 AM Page 177 In this part . . . Now that the introductions are over, it’s time to apply what you learned. In this part, you are ready to dive into the key design, coding, and session management principles and techniques that you need to know to successfully code and deploy a Facebook application. 13_277959-pp03.qxp 5/5/08 11:27 AM Page 178 Chapter 8 Developing Facebook Canvas Pages In This Chapter Deciding whether to use an FBML or iframe approach Creating a dashboard header for your application Adding navigation controls Working with editor pages AFacebook page can be divided into three rectangular blocks — the topmost menu bar, the left sidebar, and the remaining frame known as the canvas page. Most all the interaction in Facebook takes place on the canvas page. When you view a profile, the profile shows up there. Or, when you run a Facebook app, it is presented inside the canvas page. Although you cannot customize the menu bar or sidebar, you have free reign to do most anything you want inside the canvas page. From a technology perspective, you can either implement the canvas page using FBML or present an external Web site inside an iframe. (An iframe, or inline frame, is an element enabling you to embed another HTML page inside the main document.) In this chapter, you explore how to work with and add an FBML framework to your canvas pages. To FBML or iframe? That Is the Question One of the strategic decisions that you need to make when you create your Facebook application is deciding whether to use FBML or an iframe for your canvas page. The issue is more than just an implementation detail. In fact, it gets to the heart of the goals for your application. 14_277959-ch08.qxp 5/5/08 11:27 AM Page 179 FBML embraces the Facebook Platform and enables your application to become part of Facebook itself. iframes, on the other hand, enable your Web application to function inside Facebook without coding an interface that works only inside a single context (Facebook). The reasons for using FBML include the following: Has a consistent look and feel: When you use FBML, your application styles and controls automatically take on a Facebook look and feel, making it look identical to other Facebook apps. This consistency reduces the learning curve for your users and gives them instant familiarity and comfort with their surroundings. Uses FBML elements: FBML is filled with several tags, controls, and “widgets” that enable you to develop a rich app interface in minimal time. Want to add a dashboard navigation menu? With FBML, you simply need to add an fb:dashboard tag. With iframes, you need to code and style it all yourself. May offer improved performance: Facebook claims that performance is improved when you use FBML. However, that claim probably depends on the specifics of an application and is not necessarily a blanket statement. On the other hand, reasons you should consider using an iframe approach include the following: Enables existing apps to get up and running quicker: If you have an existing Web app, you usually need to do very little to integrate into Facebook using an iframe approach. Your application can perform, more or less, as is within the confines of the iframe. If you port to FBML, you are going to have to rework a lot of the presentation code. Makes it easier to maintain a common code base: When you use FBML, you will probably need to branch your code base so that you can maintain a Facebook version, a stand-alone version, and perhaps a version that fits into another network, such as Bebo or OpenSocial. However, if you use an iframe approach, you will not need to replace more generic HTML with Facebook-specific FBML. Having said that, if you are going to integrate into various social networking environments, you need to be realistic. Some platform-specific presentation code must be performed, regardless of whether you use FBML. Therefore, the iframe approach is not necessarily a cure-all for portability. Avoids JavaScript limitations: The Facebook Platform does provide scripting support, but it is more restrictive than a native HTML environment. As a result, with iframes, you are not bound to the same restrictions for using JavaScript as you would be using FBML. 180 Part III: Developing Facebook Applications 14_277959-ch08.qxp 5/5/08 11:27 AM Page 180 The decision you make will depend on your circumstances. But, if you are focused primarily on creating an app for the Facebook Platform, I highly recommend using FBML. (For more on working with iframe-based pages, see Chapter 10.) Adding a Navigation Header Using FBML When you browse the Facebook application directory, you get a variety of navigation headers, depending on whether the app takes an FBML or iframe approach as well as the extent to which the developer cared to emulate the Facebook environment. For example, consider the typical style of a Facebook app, such as Photos, as shown in Figure 8-1. fb:action links Dashboard header fb:tab-item fb:create-button fb:help link fb:tabs Figure 8-1: Navigating with Photos app. Chapter 8: Developing Facebook Canvas Pages 181 14_277959-ch08.qxp 5/5/08 11:27 AM Page 181 However, although all Facebook apps fit inside the canvas area of the page, not all will model their navigation on the Facebook style. TripAdvisor’s Local Picks app is one such example that uses an iframe approach and has a different look and feel for its navigation header (see Figure 8-2). Other third-party apps aim to follow the Facebook approach using FBML tags, such as the CDs app (such as Figure 8-3), which essentially uses the same navigation controls as does Photos. In the following sections, I walk you through creating a navigation header that emulates the Facebook look and feel. Figure 8-2: Local Picks app does not emulate the Facebook UI. 182 Part III: Developing Facebook Applications 14_277959-ch08.qxp 5/5/08 11:27 AM Page 182 Adding an fb:dashboard element With FBML, you can add a Facebook navigation header to your application using a combination of FBML elements, including fb:dashboard, fb: action, fb:create-button, fb:help, fb:tabs, and fb:tab-item. For example, suppose you want to create a new recipe application called fbRecipe. The structure for the application can include the following: Browsing sections for dinners, desserts, and appetizers Quick access to users’ and friends’ recipes A quick link to an online store for spices and other cooking ingredients A recipe discussion page A link to the app’s About page Figure 8-3: CDs looks like it could be a built-in Facebook app. Chapter 8: Developing Facebook Canvas Pages 183 14_277959-ch08.qxp 5/5/08 11:27 AM Page 183 Following the Facebook conventions, I begin by adding an fb:dashboard element: The fb:dashboard tag is used to render a dashboard header, which displays the title and icon of the application. It also serves as a container for any fb:action, fb:create-button, and fb:help tags you want to place on the page. In this example, I want to begin by placing three fb:action tags for the recipe and shopping links inside the dashboard container: My Recipes Friends’ Recipes Shop for Ingredients The fb:action element defines a link inside an fb:dashboard or a profile box’s fb:subtitle. These will be placed above the application title, just below the Facebook top menu bar. Next, the fb:create-button offers a highly visible way of performing the most common action in the app. In this case, adding a new recipe is the best candidate. I add the following inside the dashboard: Add a new recipe I add a Help link to provide quick access for users to get application assistance: Help Here’s the completed dashboard code: My Recipes Friends’ Recipes Shop for Ingredients Help Add a new recipe 184 Part III: Developing Facebook Applications 14_277959-ch08.qxp 5/5/08 11:27 AM Page 184 Figure 8-4 shows the initial page with some dummy text, and Figure 8-5 displays the page with the dashboard header added. The fb:dashboard element does not enable you to customize the display of the application title and icon in the header. If you want greater flexibility, use the fb:header element (discussed in the section “Adding a header with fb:header,” later in this chapter). Adding a tab set with fb:tabs and fb:tab-item A tab set is commonly used as a primary navigation device for applications with multiple views or modules. According to Facebook norms, tabs are placed underneath the dashboard header. In the fbRecipe app, I want to add several tabs, such as the home page and listings of dinners, desserts, and appetizers. I also want to add tabs for a discussion board and for the app’s About page. To do so, I first add an fb:tabs element to serve as a container for the tabs: Note that the order in which you place FBML tags in your source code generally dictates the display order. Therefore, if you place the fb:tabs element above fb:dashboard, the tab set will appear above the dashboard. Figure 8-5: fbRecipe’s dashboard. Figure 8-4: Starter page. Chapter 8: Developing Facebook Canvas Pages 185 14_277959-ch08.qxp 5/5/08 11:27 AM Page 185 Each tab is added to the tab set using an fb:tab-item tag. It contains four attributes: href: Specifies the URL to link to (required). title: Declares the text to be displayed on the tab (required). selected: Indicates whether this tab is the active or selected tab in the set. If multiple tabs have selected=”true”, Facebook chooses the first encountered and ignores the rest. (Optional; default is false.) align: Enables you to specify the left or right alignment of a tab. This attribute comes in handy when you want to place tabs on the right side of the page. (Optional; default is left.) The first four are left-aligned, with the home page being the selected tab: I’d like to right-align the final two tabs (using the align=”right” attributevalue pair) to visually offset these from the other tabs: Figure 8-6 displays the results. 186 Part III: Developing Facebook Applications 14_277959-ch08.qxp 5/5/08 11:27 AM Page 186 Finally, the fb:title tag can be used to specify the title of the page inside the browser window (much like the title meta tag is used in a normal HTML page). Here’s the code: the ultimate recipe box you’ve never ever heard of Facebook already specifies Facebook | YourAppName as the title of the page. Any text you place in the fb:title tag is appended to it. Therefore, the following text is the title for the fbRecipe home page: Facebook | fbRecipe | the ultimate recipe box you’ve never ever heard of All of this header code can then be included as part of each canvas page of the app, tweaking the selected attribute as needed for the tab items. The full page listing is as follows: the ultimate recipe box you’ve never ever heard of My Recipes Friends’ Recipes Shop for Ingredients Help Add a new recipe Figure 8-6: Tabs for the fbRecipe app. Chapter 8: Developing Facebook Canvas Pages 187 14_277959-ch08.qxp 5/5/08 11:27 AM Page 187

Welcome to fbRecipe

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
See Chapter 10 for full details on working with styles. Adding a header with fb:header The fb:header tag is an alternative to the fb:dashboard tag for adding a header to your application. Although you cannot insert fb:action or fb: help links in an fb:header, fb:header does provide greater flexibility than fb:dashboard in terms of displaying your application title. To modify your application title, specify it as content in the fb:header tag (see Figure 8-7): fbRecipe, the recipe box for the masses Figure 8-7: Customized application title. 188 Part III: Developing Facebook Applications 14_277959-ch08.qxp 5/5/08 11:27 AM Page 188 To remove the icon, use the icon attribute (see Figure 8-8): fbRecipe, the recipe box for the masses To add a border to the bottom of the header, use the decoration attribute, specifying add_border: fbRecipe, the recipe box for the masses A 1px solid #ccc border is displayed at the bottom of the header block, as shown in Figure 8-9. Note that, for style considerations, this option should not be used in combination with an fb:tabs set. To get rid of all the 20px padding surrounding the header, use the following code (see Figure 8-10): fbRecipe, the recipe box for the masses Figure 8-10: Getting rid of the header padding. Figure 8-9: A bottom border can be added to the fb: header. Figure 8-8: Application title sans icon. Chapter 8: Developing Facebook Canvas Pages 189 14_277959-ch08.qxp 5/5/08 11:27 AM Page 189 Or, to get rid of just the bottom 20px padding, use the following (see Figure 8-11): fbRecipe, the recipe box for the masses Finally, if you would like to add an image banner to the top of the canvas page, the fb:header element is often the best way to include it. Instead of adding text for the application title, use an img element instead. Be sure to use the icon=”false” to prevent Facebook from overlaying the app icon on top of your banner image. Here’s the code I used: Figure 8-12 displays the results. Creating an Editor Form Page FBML provides a set of editor-related controls that enable you to quickly assemble a two-column data entry form on your canvas page. The fb:editor element serves as the form container for various controls (see Table 8-1). Figure 8-12: The fb: header tag is ideal when you need to use an image header. Figure 8-11: Eliminating the bottom padding with the shorten option. 190 Part III: Developing Facebook Applications 14_277959-ch08.qxp 5/5/08 11:27 AM Page 190 Table 8-1 Editor Controls FBML Element Description fb:editor Renders a two-column form fb:editor-button Renders a submit button (the FBML equivalent of an input type=”submit”) fb:editor-buttonset Serves as a container for buttons inside an fb:editor element fb:editor-cancel Renders a Cancel button fb:editor-custom Serves as a container for FBML content fb:editor-date Renders a two-drop-down list box set for date selection (can only have one of these tags per page) fb:editor-divider Displays a horizontal line separator fb:editor-month Renders a month selector control fb:editor-text Renders a text control (the FBML equivalent of an input type=”text”) fb:editor-textarea Renders a multiline text control (the FBML equivalent of a textarea) fb:editor-time Renders a three-drop-down list box set for time selection The fb:editor element combines aspects of the table and form elements from the HTML world. Like a table, it provides a two-column structure of one or more rows. But, like a form, it contains data-capturing elements that are submitted when a Submit button is clicked. Each of the editor controls you place inside of fb:editor is positioned as a new row in the invisible table structure. The label attribute of the control is placed in the left column, and the control itself is rendered in the right. The fb:editor element itself has three attributes: required: Specifies the URL that the form is being submitted to (required). width: Determines the width (in pixels) of the editor form. (Optional; defaults to 425 pixels.) labelwidth: Indicates the pixel width of the label column. (Optional; defaults to 75.) Chapter 8: Developing Facebook Canvas Pages 191 14_277959-ch08.qxp 5/5/08 11:27 AM Page 191 The fb:editor tag is automatically centered on the canvas page. So, if you want to adjust its position, you can play with the lengths of the width and labelwidth controls. To demonstrate, consider an editor page to be added to fbRecipe for adding a new recipe. Here are the data elements I want to capture: Name of the recipe, best captured using the standard fb:editor-text control. Category of the recipe (appetizer, dinner, dessert, or other), which is best displayed as a traditional select drop-down list (because no equivalent fb:editor-* controls exist). Ingredients and Directions are memo-type fields that can be captured with the fb:editor-textarea control. Serving size, like recipe category, is best displayed as a select dropdown list. To create this editor form, I begin by defining the fb:editor element: I added the action attribute, but I’ll hold off specifying the width and labelwidth until later. An fb:editor-text tag is added to capture the recipe name: To add the select drop-down box, I need to enclose it in an fb:editorcustom element. Inside this control, I can then add a standard HTML element: The fb:editor-custom element can be used to contain other familiar HTML elements too, including password fields, radio buttons, and check boxes. The label attribute value of fb:editor-custom is displayed in the label column, and the HTML control is rendered on the right.
The ingredients to a recipe are captured using a memo-style field, the fb:editor-textedit tag: The recipe directions are also captured using an fb:editor-textedit. However, I also want to add a special note to users that I want to be displayed above the memo box. To do so, I add text inside an fb:editorcustom tag. Here are both lines: Please be as descriptive as possible to help fellow fbRecipians: The serving size is displayed using a select drop-down box, wrapped inside an fb:editor-custom tag: Finally, no Web form is complete without buttons. Facebook editor forms use an fb:editor-buttonset tag that serves as a container for buttons (fb: editor-button, fb:editor-cancel) that you want to place. Each of the buttons is rendered next to each other in the order in which they appear in the source code. For this example, I would like to include an Add and a Cancel button: The fb:editor-button element serves as a Submit button for the form. The optional value attribute indicates the text to appear on the button when rendered. The fb:editor-cancel element displays Cancel when no value attribute is specified. Here’s the full source code to the editor form: Chapter 8: Developing Facebook Canvas Pages 193 14_277959-ch08.qxp 5/5/08 11:27 AM Page 193 Please be as descriptive as possible to help fellow fbRecipians: Figure 8-13 shows the results when the form is displayed in the browser.

No comments