Making a Custom Facebook Wall with jQuery Templates

In this tutorial, we are going to create our own version of Facebook's wall. We will be using Facebook's Graph API with jQuery, and the template plugin. The jQuery.tmpl plugin will allow us to define templates within our page, and convert the posts we've obtained from the API into a real HTML page.

You can use today's example to display a feed of the latest posts on your FB page or profile on your website.

Before we begin, lets say a few words about the Facebook API.

Update on June 19th, 2011: Recently Facebook introduced some changes to their API that broke this script. They now require that you use an access token in order to fetch the page feed, used by this example. The last section of this tutorial explains how to obtain such an access token.

The Graph API

The Graph is Facebook's solution to providing an interface to every object that exists in the site, along with its connections to other objects. Every page that you see on the site has a corresponding graph representation, be it a user, photo, group, status update or anything else. The API also supports JSONP requests, which makes it really easy to use with jQuery.

We will be using two API datapoints - one for selecting the latest posts, and the other for selecting the full name and avatar of the page. You can see sample responses below:

http://graph.facebook.com/smashmag/posts/

{
    "data": [{
        "id": "45576747489_10150136051797490",
        "from": {
            "name": "Smashing Magazine",
            "category": "Website",
            "id": "45576747489"
        },
        "message": "Creating a sphere with 3D CSS",
        "picture": "http://platform.ak.fbcdn..",
        "link": "http://bit.ly/epqBBv",
        "name": "Creating a sphere with 3D CSS \u2013 Paul Hayes",
        "caption": "www.paulrhayes.com",
        "description": "A professional slice of newly..",
        "icon": "http://photos-d.ak.fbcdn.net/photos..",
        "actions": [{
            "name": "Share",
            "link": "http://www.facebook.com/share.."
        }],
        "type": "link",
        "application": {
            "name": "Sendible",
            "id": "26065877776"
        },
        "created_time": 1301325483,
        "updated_time": 1301325483,
        "likes": {
            "data": [{
                "name": "Zome Lia",
                "id": "100000643422735"
            }],
            "count": 16
        }
    }]
}

The JSON response above contains information on every one of the posts published by Smashing Magazine. Some of the fields contain data about the creation/modification date, number of likes and comments, title and description, and a type. This request could return status updates, shared links, uploaded photos and videos, and more.

We also need to make an additional request so we can obtain the avatar, associated with the page (it is not contained in the post responses):

http://graph.facebook.com/smashmag/

{
    "id": "45576747489",
    "name": "Smashing Magazine",
    "picture": "http://profile.ak.fbcdn.net/hp..",
    "link": "http://www.facebook.com/smashmag",
    "category": "Website",
    "likes": 42696,
    "website": "http://www.smashingmagazine.com/",
    "username": "smashmag",
    "company_overview": "Founded in September 2006..",
    "mission": "The offical Smashing Magazine pa..!",
    "products": "Looking for a web design job? Che.."
}

The picture field above gives us what we need. It is a bit of a waste to request so much data, so in the plugin we are actually limiting the returned fields to only what we need.

The Templates

Now lets say a few words about the jQuery templates. As the Graph API returns valid JSON data, it is a great candidate to experiment with jQuery's template plugin. This official plugin enables us to define HTML building blocks with an easy to use markup. This saves us from having to manually create HTML elements, concatenate strings and escape character sequences.

The templates themselves may be inserted inline in a special script tag, or can be received via an AJAX call from a separate file. In this tutorial, I've chosen the first approach as it is simple and straightforward.

Each template has the following form:

<script id="someID" type="text/x-jquery-tmpl">
<!-- HTML markup coupled with template tags -->
</script>

This is a script tag which, because of the type attribute, is not recognized by the browser, so it is not evaluated nor shown. What is more, its content is treated as character data and is not parsed, which is perfect for the task of holding our templates. We can then use jQuery's tmpl() method and render it into actual HTML markup (more on that in a moment).

Here is the first template, which creates the heading of the page:

<script id="headingTpl" type="text/x-jquery-tmpl">
<h1>${name}<span>on Facebook</span></h1>
</script>

The ${} template tag gets replaced with the value of the name property of the object, that is passed to the tmpl() method, which in our case is the name of the facebook page.

For a complete list of template tags and methods, read through the jQuery Template documentation.

The other template, which displays the individual posts is a bit more complex and employs some of the more advanced templating features:

<script id="feedTpl" type="text/x-jquery-tmpl">
<li>
    <img src="${from.picture}" />

    <div>
        <h2><a href="http://www.facebook.com/profile.php?id=${from.id}" target="_blank">${from.name}</a></h2>
        <p>{{html message}}</p>
        {{if type == "link" }}
            <div>
                {{if picture}}
                    <img src="${picture}" />
                {{/if}}
                <div>
                    <p><a href="${link}" target="_blank">${name}</a></p>
                    <p>${caption}</p>
                    <p>${description}</p>
                </div>
            </div>
        {{/if}}
    </div>

    <p>${created_time} ·
    {{if comments}}
        ${comments.count} Comment{{if comments.count>1}}s{{/if}}
    {{else}}
        0 Comments
    {{/if}} ·
    {{if likes}}
        ${likes.count} Like{{if likes.count>1}}s{{/if}}
    {{else}}
        0 Likes
    {{/if}}
    </p>

</li>
</script>

Inside the template tags we can have any JavaScript expressions, even method and function calls. This is especially helpful when building the {{if}} statements, as you can see from the code above, where we check the number of likes and comments.

One feature of the ${} tag is that it escapes the textual value before inserting it into the template. However in some cases this is not what you need. For example the message variable holds HTML code that we want to display as is. This is why we use the {{html}} tag instead, which preserves the original format of the code.

And here is the HTML document we end up with:

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Making a Custom Facebook Wall with jQuery | Tutorialzine Demo</title>
<link rel="stylesheet" type="text/css" href="css/styles.css" />

</head>
<body>

<div id="page">

    <div id="wall"></div>

</div>

<!-- jQuery templates. Not rendered by the browser. Notice the type attributes -->

<script id="headingTpl" type="text/x-jquery-tmpl">
<h1>${name}<span>on Facebook</span></h1>
</script>

<script id="feedTpl" type="text/x-jquery-tmpl">
<li>
    <img src="${from.picture}" class="avatar" />

    <div class="status">
        <h2><a href="http://www.facebook.com/profile.php?id=${from.id}" target="_blank">${from.name}</a></h2>
        <p class="message">{{html message}}</p>
        {{if type == "link" }}
            <div class="attachment">
                {{if picture}}
                    <img class="picture" src="${picture}" />
                {{/if}}
                <div class="attachment-data">
                    <p class="name"><a href="${link}" target="_blank">${name}</a></p>
                    <p class="caption">${caption}</p>
                    <p class="description">${description}</p>
                </div>
            </div>
        {{/if}}
    </div>

    <p class="meta">${created_time} ·
    {{if comments}}
        ${comments.count} Comment{{if comments.count>1}}s{{/if}}
    {{else}}
        0 Comments
    {{/if}} ·
    {{if likes}}
        ${likes.count} Like{{if likes.count>1}}s{{/if}}
    {{else}}
        0 Likes
    {{/if}}
    </p>

</li>
</script>

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
<script src="js/jquery.tmpl.min.js"></script>
<script src="js/script.js"></script>

</body>
</html>

The #wall div is going to be dynamically populated with the Graph API data, after it has been rendered using our templates. You can see the templates themselves at the bottom of the file. Before the closing body tag, I have included the jQuery library, the jQuery.tmpl plugin, and our script.js file, which we will be discussing next.

jQuery Code

As we have all the pieces in place, we can finally get down to writing our facebook wall plugin.

script.js

// Creating our plugin.

(function($){

    $.fn.facebookWall = function(options){

        options = options || {};

        if(!options.id){
            throw new Error('You need to provide an user/page id!');
        }

        // Default options of the plugin:

        options = $.extend({
            limit: 15   // You can also pass a custom limit as a parameter.
        },options);

        // Putting together the Facebook Graph API URLs:

        var graphUSER = 'http://graph.facebook.com/'+options.id+'/?fields=name,picture&callback=?',
            graphPOSTS = 'http://graph.facebook.com/'+options.id+'/posts/?callback=?&date_format=U&limit='+options.limit;

        var wall = this;

        $.when($.getJSON(graphUSER),$.getJSON(graphPOSTS)).done(function(user,posts){

            // user[0] contains information about the user (name and picture);
            // posts[0].data is an array with wall posts;

            var fb = {
                user : user[0],
                posts : []
            };

            $.each(posts[0].data,function(){

                // We only show links and statuses from the posts feed:
                if(this.type != 'link' && this.type!='status'){
                    return true;
                }

                // Copying the user avatar to each post, so it is
                // easier to generate the templates:
                this.from.picture = fb.user.picture.data.url;

                // Converting the created_time (a UNIX timestamp) to
                // a relative time offset (e.g. 5 minutes ago):
                this.created_time = relativeTime(this.created_time*1000);

                // Converting URL strings to actual hyperlinks:
                this.message = urlHyperlinks(this.message);

                fb.posts.push(this);
            });

            // Rendering the templates:
            $('#headingTpl').tmpl(fb.user).appendTo(wall);

            // Creating an unordered list for the posts:
            var ul = $('<ul>').appendTo(wall);

            // Generating the feed template and appending:
            $('#feedTpl').tmpl(fb.posts).appendTo(ul);
        });

        return this;

    };

    // Helper functions:

    function urlHyperlinks(str){
        return str.replace(/\b((http|https):\/\/\S+)/g,'<a href="$1" target="_blank">$1</a>');
    }

    function relativeTime(time){

        // Adapted from James Herdman's http://bit.ly/e5Jnxe

        var period = new Date(time);
        var delta = new Date() - period;

        if (delta <= 10000) {    // Less than 10 seconds ago
            return 'Just now';
        }

        var units = null;

        var conversions = {
            millisecond: 1,     // ms -> ms
            second: 1000,       // ms -> sec
            minute: 60,         // sec -> min
            hour: 60,           // min -> hour
            day: 24,            // hour -> day
            month: 30,          // day -> month (roughly)
            year: 12            // month -> year
        };

        for (var key in conversions) {
            if (delta < conversions[key]) {
                break;
            }
            else {
                units = key;
                delta = delta / conversions[key];
            }
        }

        // Pluralize if necessary:

        delta = Math.floor(delta);
        if (delta !== 1) { units += 's'; }
        return [delta, units, "ago"].join(' ');

    }

})(jQuery);

We are using the $.getJSON functions to request information from the Graph API. But you may notice that we are not using it as we have in previous tutorials, namely by providing a callback function as its second parameter. This is because we want both calls to the Graph API to be run in the same time (speed all the way), which is not possible with a simple callback.

As of jQuery 1.5, all AJAX methods return a deferred object, which basically allows us to group a number of AJAX calls in a $.when(). After both of the AJAX requests complete successfully, the done method is executed once.

After this, we can simply render the templates:

// Rendering the templates:
$('#headingTpl').tmpl(fb.user).appendTo(wall);

// Creating an unordered list for the posts:
var ul = $('<ul>').appendTo(wall);

// Generating the feed template and appending:
$('#feedTpl').tmpl(fb.posts).appendTo(ul);

The tmpl() method takes a JavaScript object or array, and renders the template once per each element. The templates are specified by their ids (the #headingTpl and #feedTpl script elements in our case).

Finally we only have to call the plugin in document.ready with the ID of your page, and your access token (more on this in a moment):

$(document).ready(function(){

    // Calling our plugin with a page id:
    $('#wall').facebookWall({
        id:'smashmag',
        access_token:'19304297594165|ZGyz1d0clt2XO3AyrjHmrKORo'
    });

});

Obtaining an access token

This section was added on June 19, 2011 to reflect the changes that Facebook introduced in their API. Namely to require an access token to fetch the page feed.

The first step to obtaining an access token is registering as a developer on http://developers.facebook.com. After this you will need to create a new Facebook App. It is a simple process and you don't need to enter any data except for the name of the application. This will give you an App ID and an App Secret, which you can see from the "My Apps" page.

Next you need to visit the following URL, replacing APP_ID and APP_SECRET with the values for your App:

https://graph.facebook.com/oauth/access_token?grant_type=client_credentials&client_id=APP_ID&client_secret=APP_SECRET

This will give you a string, similar to this:

access_token=19304297594165|ZGyz1d0clt2XO3AyrjHmrKORo

This is your access token. You will need to include the string after the equal sign when calling the facebookWall plugin in the previous section.

With this our custom Facebook wall is complete!

Wrapping Up

Hopefully in today's tutorial, you saw that templates are a great tool to have in your jQuery arsenal. The template plugin makes it really easy to define, render and store templates. Combined with some of its more advanced features, you can create easy to maintain web applications, without getting tangled in lengthy chains of jQuery selectors.

Do you like this tutorial? How would you improve the example? Share your thoughts in the comment section below.