This trail map will build on the Suggestion application started in trail map #3. We will extend that Suggestion application such that it will now use FBML tags and both Ringside and Facebook API calls.

We will also add the ability to rate suggestions using Ringside API Extensions.

For a complete list, with explanation and examples, of the APIs and FBML used in this trail, please see the Appendix found at the end of this trail.

Setup

All files for this trail can be found in one of three places:

1. [installation_dir]/apps/ringside/htdocs/trail_map_4 (if you used the Ringside installer)
2. Download it here as either a tarball (for Linux/Mac) or a zip file (for Windows)
3. Build it yourself. This assumes you have the Ringside source checked out from SVN. Go to your working copy's /demo-apps directory and run the build by executing phing. The source for this trail will then be located here (relative to your SVN working copy): dist\demo-apps\stack\apps\ringside\htdocs\api\trail_map_4

Please see trail #2 for full instructions on how to deploy an application to a Ringside Server. Just make sure to set your callback url to the index.php in the trail_map_4 project. This file acts as your controller/action class. As you learned in trail #3, be sure to update the values in config.php.

Implementation

Make sure your project contains the following files from trail #4:

If you read and/or completed trail #3, you will notice the project contains similar file names and setup.

index.php is our controller/action class. This is the file that decides exactly what to display based on the parameters passed in.

$ringsideClient = new RingsideApiClients( Config::$api_key, Config::$secret ); 
$ringsideClient->require_frame(); 
$userid = $ringsideClient->require_login(); 
$rest = new RingsideRestClient($ringsideClient->api_client); 
$name = $rest->delegate->users_getInfo($userid, "first_name");

As in trail #2 the first thing we do is instantiate our client, require the user to login, and then get the logged in user's name for display purposes. Please note the use of the RingsideRestClient. This is an important class because it contains API wrappers for the Ringside Ratings API, among other things.

<fb:dashboard>
   <fb:action href="/ringside/canvas.php/trail4/?action=list" >View Suggestions</fb:action> 
   <fb:create-button href="/ringside/canvas.php/trail4/?action=add" >Create a Suggestion </fb:create-button> 
</fb:dashboard>

The next thing we'll do is add our header. We can easily do this by using the <fb:dashboard> tag. Along with the standard header we want two links available to the end user - a link to "View Suggestions" and a link to "Create a Suggestion".
As you will see in a minute, the action=list and action=add are used to control what the end user sees.

echo '<fb:explanation><fb:message>
Suggestions Demo Application
</fb:message> Welcome '.$name\[0\]\['first_name'\].'</fb:explanation>';

We use the <fb:explanation> and <fb:message> tags to display a message to the end user. FBML supports most HTML tags so we could have used <div>, <p>, etc... for this as well. Because this is a demo application, we use FBML here just as an example; make sure to use what's appropriate for your application.

Based on the appropriate action passed in, we want to control what the end user sees. The following lists the actions that are supported and shows code which controls the display for each action:

action=add

This action tells us we need to display the form for adding a suggestion. The Suggestion Application states that a user can only enter suggestions for friends, see suggestions from friends, and see topics only from friends. To accomplish this we use the friends API as follows:

$friends = $rest->delegate->friends_get(); 
$friends[] = $userid; 
$topics = SuggestionUtils::getTopics($friends); 
include_once('add.php');

This code calls the friends_get method to retrieve all the UIDs of the logged in user's friends. It then adds the logged in user's id to this list, since by rule the user is allowed to see their own suggestions and topics. Then the app calls the SuggestionUtils::getTopics function which will be the same or similar to that used in trail #3.

The code for the add form is in the add.php file and is shown below:

<body> 
   <fb:editor action="/ringside/canvas.php/trail4/"> 
      <fb:editor-custom> 
         <input type="hidden" name="action" value="add_suggestion" id="action"/> 
      </fb:editor-custom> 
      <fb:editor-text label="New Topic" name="newtopic" value="newtopic"/> 
      <fb:editor-custom label="Existing Topic"> 
         <select name="existingtopic"> 
            <option selected="true" value="none">-</option> 
<?php 
foreach($topics as $topic) { 
   echo '<option value="'.$topic['owneruid'].':'.$topic['topic'].'">'.$topic['topic'].'</option>'; 
} 
?> 
         </select> 
      </fb:editor-custom> 
      <fb:editor-text label="Suggestion" name="suggestion" value="suggestion"/> 
      <fb:editor-buttonset> 
         <fb:editor-button name="submit_button" value="<?php echo $button_label ?>" /> 
         <fb:editor-cancel href="index.php?action=list" /> 
      </fb:editor-buttonset> 
   </fb:editor> 
</body>

Note that we could have chosen to use an HTML form, with div tags, and labels, but this demo is about using FBML tags and using FBML is actually easier than using HTML in this instance.

The Appendix covers the <fb:editor> tag in detail, but for this demo we needed 5 sub tags. The <fb:editor-custom> allows us to put our own input tags, such as hidden or the select tag. This is used when there is no appropriate tag in FBML or when you want to do something special not supported by a tag, such as call a javascript method. See the System Application: Registration for an example of using javascript within an <fb:editor-custom> tag.

The <fb:editor-text> tag simply displays a text box. We need this for new topics and for the suggestion itself.

Once the data is filled out we need to allow the user to either 1) submit the suggestion or 2) change their mind and cancel. This is accomplished with the <fb:editor-buttonset> which creates a button layout which you can add buttons to. In this case we need the <fb:editor-button>, which is a submit button, and the <fb:editor-cancel> which by default will display a link with the word "cancel".

Once the user adds a form, we need a way to handle the creation of the suggestion. This is done with a new action call add_suggestion.

add_suggestion

SuggestionUtils::createSuggestion($topic, $suggestion, $userid, $ownerid); 
showSuggestions($rest, $userid);

The add_suggestion action simply pulls the form values from the $_REQUEST and creates the $topic, $suggestion, and $ownerid variables. Once the suggestion is created we call our method to show all the suggestions for this user.

function showSuggestions(RingsideRestClient $rest, $uid) { 
   $friends = $rest->delegate->friends_get(); 
   $friends[] = $uid; 
   $suggestions = SuggestionUtils::getSuggestions($friends); 
   
   // Now get ratings 
   $iids = array(); 
   foreach($suggestions as $suggestion) { 
      $iids[] = $suggestion['sid']; 
      $rest->items_setInfo($suggestion['sid'], '/ringside/canvas.php/trail4', '/ringside/canvas.php/trail4', null); 
      $ratings = $rest->ratings_get($iids); 
   } 
} 
include_once('list.php');

This method creates the friends list in exactly the same way as the add action which allows us to query all of the suggestions this user is allowed to see. Once we have the suggestions, we want to get this user's rating for each suggestion. There are two parts to this process.

1. For each suggestion we need to make sure there is a corresponding Item ID. We accomplish this by calling the Item API's set info method: $rest->items_setinfo(item_id, url, ref_url, type). Please see the Appendix for details on this API call.
2. Once we have the Item IDs and are assured the Items exist in the system we can make a call to the Ratings API: $rest->ratings_get(item_ids). Please see the Appendix for details on this API call.

With all the data gathered we now simply need to show our template page that loops through the data creating our display:

$lasttopic = 'bogus'; 
$firstname = ''; 
foreach( $suggestions as $suggestion ) { 
   $topic = $suggestion['topic']; 
   try { 
      $names = $rest->delegate->users_getInfo( $suggestion['uid'], "first_name" ); 
      $name = $names[0]; 
      $firstname = $name['first_name']; 
   } catch( Exception $e ) { 
      $firstname = 'Friend of Friend'; 
   } 
   if( $topic != $lasttopic ) { 
      echo '<br/>'; 
      echo "<div>Topic: $topic</div>"; 
   } 
   $lasttopic = $topic; 
   $sid = $suggestion['sid']; 
   $yes = 'black'; 
   $no = 'black'; 
   foreach($ratings as $rating) { 
      $iid = $rating['iid']; 
      if($iid == $sid) { 
         $vote = $rating['vote']; 
         if($vote == 1) { 
            $yes = 'green'; 
         }else { 
            $no = 'red'; 
         } 
      } 
   } 
   $vote_string = '<a href="index.php?action=rate&vote=1&iid='.$suggestion['sid'].
'" ><font color="'.$yes.'">yes</font></a>\|<a href="index.php?action=rate&vote=0&iid='.$suggestion['sid'].
'" ><font color="'.$no.'">no</font></a> '; 
   echo '<div>'.$vote_string.$suggestion['suggestion'].' posted by '.$firstname.' at '.$suggestion['created'].'</div>'; 
}

Please note for this demo we are simply doing a 0 or 1 rating, basically for yes/no. The ratings API supports any type of numerical vote so we could just as easily used a scale of 1-5. Also notice that we used the ratings_get call which is based on the logged in user. We could have also, or instead, called the ratings_getAverage call which would have told us the average vote for each suggestion.

Notice that in this example if a user clicks on yes or no it calls back to our index.php with the action set to rate.

rate

The rate action tells our controller that it needs to call the ratings API to set a rating. We do this with the following code:

$iid = $_REQUEST['iid']; 
$vote = $_REQUEST['vote']; 
$rest->ratings_set($iid, $vote, null);

The ratings_set call allows us to send a vote to the server for this item ID. Note in this example the vote is 0 or 1, but as stated previously the API allows any integer value, so your application has full control over what ratings can be set on any item. Also take note that the ratings API takes a type.

Appendix

FBML Tags

fb:dashboard

The Dashboard tag renders a standard dashboard header.

The Dashboard tag does not take any parameters, but it does take the following three optional elements:

• fb:action
• fb:create-button
• fb:help

<fb:dashboard>
   <fb:action href="new.php">Create a new photo album</fb:action>
   <fb:action href="you.php">Photos of You</fb:action>
</fb:dashboard>

The create button can be used in your application to load a new form, in this case on new.php, for adding things to your application:

<fb:dashboard>
   <fb:create-button href="new.php">Create a new photo album</fb:create-button>
</fb:dashboard>

fb:editor

The <fb:editor> tag creates a form with two columns.

NOTE: The form generated by <fb:editor> only submits data via the POST method.

The following attributes can be used with the <fb:editor> tag:

To create the body of the form the <fb:editor> tag accepts the following elements:

• fb:editor-text
• fb:editor-textarea
• fb:editor-time
• fb:editor-month
• fb:editor-date
• fb:editor-divider
• fb:editor-buttonset
• fb:editor-button
• fb:editor-cancel
• fb:editor-custom

Example:

<fb:editor action="?do-it" labelwidth="100">
   <fb:editor-text label="Title" name="title" value=""/>
   <fb:editor-text label="Author" name="author" value=""/>
   <fb:editor-custom label="Status">
      <select name="state">
         <option value="0" selected>have read</option>
         <option value="1">am reading</option>
         <option value="2">want to read</option>
      </select>
   </fb:editor-custom>
   <fb:editor-textarea label="Comment" name="comment"/>
   <fb:editor-buttonset>
      <fb:editor-button value="Add"/>
      <fb:editor-button value="Recommend"/>
      <fb:editor-cancel />
   </fb:editor-buttonset>
</fb:editor>

APIs

In order to use an API you will need the following client files:

• RingsideApiClientsRest.php
• RingsideRestClient.php
• facebookapi_php5_restlib.php
• RingsideApiClientsConfig.php

To call an API is as simple as instantiating the Rest Client and calling a function. The constructor for the RingsideApiClientsRest is:

public function __construct($api_key, $secret, $session_key = null, $url = null, $network_key = null);

For RingsideRestClient:

public function __construct($delegate);

Example:

$api = new RingsideApiClientsRest($my_api_key, $my_secret, null, $ringside_server_url, null);
$rest = new RingsideRestClient($api);
// Available function prototypes for the apis used in this trail map 
// function profile_setFBML($markup, $uid = null, $profile='', $profile_action='', $mobile_profile='')
// public function ratings_set($iid, $vote, $type = null) 
// public function ratings_get($iids, $uids = null) 
// public function ratings_getAverage($iid, $uids = null, $type = null) 
// public function items_setInfo($iid, $url, $refurl, $datatype = null) 
// Set profile to some fbml $pic_url = ='http://myserver.com/images/mypic.png'; 
$fbml = "<img src'$url'/>"; 
$rest->profile_setFBML($fbml, null, null, null, null); 
// Now let's let people rate that pic 
// make sure the items is created and get the id 
$iid = "pic_id"; 
// iid can be anything, just needs to be unique 
$iid = $rest->items_setInfo($iid, $pic_url, $pic_url, null); 
$rest->ratings_get(array($iid), null);