callMethodPost() is a function I modified from Dominic Watson’s original callMethod() in his FBML Starter Kit. I decided to separate this function into two functions: callMethodGet() and callMethodPost(). Since you will be either getting or posting data, I felt that it was easier to separate the methods and call them according to what action you are taking.

<cffunction name=”callMethodPost” access=”public” output=”false” returntype=”any” hint=”I act as a raw interface to the Facebook API and return the xml string response from the facebook server.”>
<cfargument name=”method” type=”string” required=”yes” />
<cfargument name=”params” type=”struct” required=”no” default=”#StructNew()#” />
<cfargument name=”filepath” type=”string” required=”no” />

<cfset var result = StructNew() />
<cfset var key = “”>
<cfset this._tickCount = TimeFormat(now(), “hh:mm:ss”) >

<!— add params to the param struct —>
<cfset StructInsert(arguments.params, “method”, arguments.method) />
<cfset StructInsert(arguments.params, “api_key”, variables._apiKey) />
<cfset StructInsert(arguments.params, “v”, variables._apiVersion) />
<cfset StructInsert(arguments.params, “call_id”, this._tickCount) />

<!— add the signature [sig] —>
<cfset StructInsert(arguments.params, “sig”, generateSignature(arguments.params)) />

<cfhttp url=”#variables._server#” method=”post” multipart=”yes” redirect=”no”>
<cfloop collection=”#arguments.params#” item=”key”>
<cfhttpparam name=”#key#” value=”#arguments.params[key]#” type=”formfield” />
</cfloop>
<cfhttpparam name=”filename” file=”#arguments.filepath#” type=”file” />
</cfhttp>

<cfreturn cfhttp.FileContent />
</cffunction>

Part 1 of 3: Using the Feed Preview Console
Part 2 of 3: Creating the feedHandler.cfm page
Part 3 of 3: Creating the form and calling the ajax window

Creating a one line, short story and full story feed for your wall might sound really tough. You have to use json and if you are using ColdFusion, have very little documentation. Well I’m here to change that .

Really all you NEED to publish a feed on your wall is:

1. a registered template bundle id
2. a feed handler page
3. a form to instantiate your feedStory call

*note: using the feed preview console allows you to register a template bundle id manually. if you wish to create multi-feed posts, you have to use feed.registerTemplateBundle and feed.publishUserAction. this allows you to create multi-feed posts, however, you are limited to 100 registered bundles. before you reach your limit, you may want to call feed.getRegisteredTemplateBundles and feed.deactivateTemplateBundleByID. these two api calls will give you breathing room for bundles you are not using.

Register a template_bundle_id

You MUST use the Feed Preview Console Facebook gives you. http://developers.facebook.com/tools.php?feed

When you get to this screen it can be a bit intimidating but I promise you it’s really simple. The field to look at here is the ‘Sample Template Data’. This field makes the variable {*company*} available in your json response for example. To add a new variable to the flow just do this: {“myage”:”26″}. SIMPLE!

Now you can make a sentence like so, Gavin works for {*company*} in the city of {*city*} and is {*myage*} years old. Where {*company*} = Facebook, {*city*} = Palo Alto and {*myage*} = 26. Now it should start to make sense here.

As you browse over the console you start to see your entire layout for a one-line, short story and full story wall post. I chose not to use ‘Sample Target IDs’ but if you want to incorporate what one user does with another, be sure to leave the Sample IDs Facebook throws in there for you. From here, it should make pretty good sense as to what you should do with the Feed Preview Console. The only other thing to mention is images will only show in the ‘Short Story’ tab and should be utilized as imagery grabs the eye of users.

Click ‘Preview’ and if you like your sample bundle, click Register Template Bundle. This will open an ajax window with your template_bundle_id. You can deactivate any Template Bundles you are not using by clicking on the ‘Registered Templates Console’ tab. (again, it’s a good idea to deactivate non-used bundles as you are limited to 100 registered).

Phew, Now let’s make our feedHandler.cfm page

We need to create a feed handler page in order to output a json value. The ONLY purpose of this page is to return json, nothing else. This will be a typical coldfusion page that can have dynamic values and create dynamic feeds. Lets take a look at some code below:

<cfoutput>
<!— below is your json formatted ‘json’ variable —>
<cfset json = ‘{“content”:
{“feed”:
{“template_id”:#application.template_bundle_id#,
“template_data”:{“company”:”#application.appNameCap#”,
“link”:”<a href=”#application.fburl#”>#application.appNameCap#</a>”,
“here”:”<a href=”#application.fburl#”>clicking here</a>”,
“images”:[{"src":"#url.photo#", "href":"#url.photo#"}]
}
}
},
“method”:
“feedStory”
}’ />

<!— output your json response —>
#json#
</cfoutput>

As I mentioned earlier, the whole purpose of this page is to return the #json# variable. The variable we set simply passes in a template_id, your company name, your facebook url and a photo. Make note that you can use regular HTML in your variable ie. <a href… as I have above. After looking at this we can see this is not too tough and if you go to feedHandler.cfm directly, you will see a format much like this.

{“content”: {“feed”: {“template_id”:29191437598, “template_data”:{“company”:”Humorous”, “link”:”Humorous“, “here”:”clicking here“, “images”:[{"src":"yourphoto.jpg", "href":"yourphoto url"}] } } }, “method”: “feedStory” }

With this output Facebook has almost everything it needs to create your one line, short story and full story ajax window. The only thing left is to call the window through a form. You can call your ajax window with the code below.

Calling Our Ajax Window with a FORM

<form fbtype=”feedStory” action=”#application.faceBookPath#/#application.appNameLow#/feedHandler.cfm?photo=#application.urlPath#/extract/#url.pic#.jpg”>
<input type=”submit” value=”Publish” label=”Publish This Photo to Your Wall” />
</form>

The MOST IMPORTANT part of the form above is fbtype=”feedStory”. You must pass this attribute and use type submit for your submit button. Once you have your registered template, created a feed handler page and put this form in your call page….

YOU SHOULD BE SUCCESSFULLY POSTING FEEDS TO YOUR WALL FROM YOUR APPLICATION!

——————————————————————————-

callMethodGet() is a function I used from Dominic Watson’s original callMethod() in his FBML Starter Kit. I decided to separate this function into two functions: callMethodGet() and callMethodPost(). Since you will be either getting or posting data, I felt that it was easier to separate the methods and call them according to what action you are taking.

<cffunction name=”callMethodGet” access=”public” output=”false” returntype=”any” hint=”I act as a raw interface to the Facebook API and return the xml string response from the facebook server.”>
<cfargument name=”method” type=”string” required=”yes” />
<cfargument name=”params” type=”struct” required=”no” default=”#StructNew()#” />
<cfargument name=”filepath” type=”string” required=”no” />

<cfset var result = StructNew() />
<cfset var key = “”>
<cfset this._tickCount = TimeFormat(now(), “hh:mm:ss”) >

<!— add params to the param struct —>
<cfset StructInsert(arguments.params, “method”, arguments.method) />
<cfset StructInsert(arguments.params, “api_key”, variables._apiKey) />
<cfset StructInsert(arguments.params, “v”, variables._apiVersion) />
<cfset StructInsert(arguments.params, “call_id”, this._tickCount) />

<!— add the signature [sig] —>
<cfset StructInsert(arguments.params, “sig”, generateSignature(arguments.params)) />

<cfhttp url=”#variables._server#” method=”get” charset=”utf-8″ redirect=”no” throwOnError=”yes” resolveurl=”1″>
<cfloop collection=”#arguments.params#” item=”key”>
<cfhttpparam name=”#key#” value=”#arguments.params[key]#” type=”url” />
<!— <cfdump var=”#key#=#arguments.params[key]#”> —>
</cfloop>
<cfif StructKeyExists(arguments, “filepath”) and FileExists(arguments.filepath)>
<cfhttpparam type=”file” name=”file” file=”#arguments.filepath#” />
</cfif>
<!— <cfabort> —>
</cfhttp>

<cfreturn cfhttp.FileContent />
</cffunction>

Instead use FaceBook’s Tools on their developers.facebook.com site. This gives you the same responses and generates everything for you automatically.

I only mention this because a lot of developers try to hit the REST Server directly. This is not neccessary as FaceBook has developed the tools to make life easier. SO USE THEM!

——————————————————————————-

Initiating the Facebook REST Client with ColdFusion

the function below will set you up to communicate with the REST Server. There are 5 required parameters you must pass to the server in order to call any API.

Required Parameters

1. api key
2. secret key
3. canvas url
4. callback url
5. server path

<cfscript>
variables._apiKey = arguments.apiKey;
variables._secret = arguments.secret;
variables._url = arguments.url
variables._callbackURL = arguments.callbackURL;
variables._server = arguments.server;
variables._apiVersion = arguments.apiVersion;
variables._format = arguments.format;

return this;
</cfscript>
</cffunction>

——————————————————————————-

Extended Permissions are a way for your app users to grant access without asking for approval. For example, if you use the photo_upload extended permission, your users no longer have to approve an image each time they upload a photo from your application. Or if you use the email permission, your user can receive e-mails from your application.

So How Do I Call an Extended Permission?

you can request permissions in 3 different ways:

1. using the fb:prompt-permission tag
2. including the promptpermission attribute in a form
3. sending user to http://www.facebook.com/authorize.php?api_key=123456789&v=1.0&ext_perm=PERMISSION_NAME

*I prefer to use the fb:prompt-permission FBML tag. I like the cleanliness of the tag as it pops-up an ajax window members can use to quickly approve or deny a permission

<fb:prompt-permission perms=”photo_upload“>
<p><h4 style=”color:##ff0000;”>*Always Allow Photo Uploads*</h4>
(skips pending album/photo upload)</p>
</fb:prompt-permission>

*Users can revoke extended permissions through their application settings.

Before we begin to upload a photo you should know the photo_upload work flow.

All photos need to first know their destination. Whether it be a new ablum (photos.createAlbum) or an existing album (photos.getAlbum). Once a photo knows it’s destination, it can then be uploaded and be tagged (optional).

NOTE: Upload requests must be formed as a MIME multi-part message sent using POST data. Each argument, including the raw image data, should be specified as a separate chunk of form data. Facebook only supports images up to 604 pixels so be sure to scale properly before you upload.

(you may want to use the extended permission ‘photo_upload’ as well. this way the users do not have to approve each photo upload)

Lets call the photos.upload API

We will assume that were uploading to a current album (aid). Also, session_key is no longer required so you can choose whether or not you wish to pass it in.

#FBMLClient.PhotosUpload(session.fb_session_key,filename,aid)#

In this request we simply call our function ‘PhotosUpload’. We then pass in our session_key, filename (raw image)  and our aid (album id)

PhotosUpload Function

<cffunction name=”PhotosUpload” access=”public” output=”false” returntype=”any”>

<cfargument name=”session_key” type=”string” required=”true” hint=”The session key belonging to the user uploading the photo”>

<cfargument name=”filePath” type=”string” required=”true” hint=”Path to the image on the server”>

<cfargument name=”aid” type=”numeric” required=”true” hint=”The facebook ID of the album to which to upload the photo. If this has not been supplied, the photo will be uploaded to the application’s default album.”>

<cfargument name=”caption” type=”string” required=”false” default=”" hint=”Photo Caption.”>

<cfset var params = StructNew() />

<cfset params["session_key"] = arguments.session_key />

<cfset params["aid"] = arguments.aid />

<cfset params["caption"] = arguments.caption />

<cfreturn callMethodPost(“facebook.photos.upload”, params, arguments.filePath) />

</cffunction>

<fb:explanation>
<fb:message>Explanation message</fb:message>
This is the explanation message text.
</fb:explanation>

You can see you wrap your message in an explanation tags and use ‘message’ to highlight your header.

Pretty simple but very productive if your looking to display an effective message.

<fb:multi-friend-selector actiontext=”Select the friends you want to invite. (All of them.)” rows=”3″/>

The tag above will product the code below:

As you can see, you will be able to click any of the friends above and send them suggestions to interact with your application!

BELOW ARE THE PARAMETERS YOU CAN USE WITH THIS TAG