Implementing Facebook services on Textpattern articles via FBML

Facebook provides a couple standard ways to get their services (such as comments, like buttons etc) integrated into your website, it’s quite straightforward to get those services (plugins) to work on a Textpattern CMS powered website.

You could insert Facebook services as a simple iframe, but by far the more flexible method is to use their FBML option – it’s trickier to set up initially but provides much more feedback and features, you can also make those features load asynchronously so they don’t hinder the rest of the page from rendering.

Even if you don’t directly want to add Facebook features to your site (and there are plenty of valid reasons for that), you can still benefit by adding the Open Graph meta data since many users have Facebook plugins installed directly into their browser of choice which let them ‘like’ and ‘send’ a page anyway, even if the page itself has no Facebook button embedded directly in it. Note that HTML5 format code is used in this tutorial, so add any self-enclosing tags /> and any other necessary attributes if you are coding for XHTML instead.

Getting started

First you’ll need to register as a developer on Facebook, in order to retreive your Facebook app id code. Follow their instructions and you’ll be issued with a unique ID for your website.

In very top of your page template, above the <!doctype html> tag, add the following snippet, this checks whether the browser user-agent is actually the Facebook spider – the reason for using this is explained below in the ‘Open Graph protocol’ section…

<txp:php>
  function is_facebook(){
  if(!(stristr($_SERVER["HTTP_USER_AGENT"],'facebook') === FALSE))
  return true;
  }
</txp:php>

Open graph protocol

Add this code into the head meta section of your page template…

<txp:if_individual_article>
  <txp:output_form form="meta_sharing" />
</txp:if_individual_article>

Create a ‘misc’ type form named ‘meta_sharing’, this form will utilise the variable you set in the PHP code at the top of the page template. The reason? The FBML method relies on using the Open Graph protocol, unfortunately that protocol does not currently validate as HTML5, so you’ll use the variable to check the user-agent and only provide the Open Graph code to the Facebook spider, thus allowing the code to be effectively hidden from other user-agents (and not affect the validity). This may change in the future but here and now it’s a good method – and although Facebook has proposed Open Graph as a universal protocol, only they seem to use it in any meaningful way at present.

If you are not bothered about totally valid HTML5 code then you can safely omit the variable and PHP code altogether, it will not stop the page from working at all.

<txp:if_variable name="is_facebook" value="">
  <meta property="og:title" content="<txp:title no_widow='0' />"> 
  <meta property="og:description" content="<txp:excerpt />">
  <meta property="og:type" content="article">
  <meta property="og:image" content="<txp:site_url />images/style/site-logo.png">
  <meta property="og:url" content="<txp:site_url /><txp:page_url />">
  <meta property="og:site_name" content="<txp:site_name />">
  <meta property="fb:appid" content="{YOUR_FACEBOOK_APPLICATION_ID}">
</txp:if_variable>

Replace {YOUR_FACEBOOK_APPLICATION_ID} with your own unique Facebook app id.

Note on images: The example above uses a static site branded logo for the og:image meta, you could of course use any image, including a <txp:article_image /> tag. But for branding reasons you might prefer to use a universal logo for all your Facebook correspondence.

Note on excerpt: The example above populates the og:description meta using <txp:excerpt />. That relies on your setting the write page option for Excerpt Markup to ‘Convert linebreaks’ because we want to strip out the <p> tag from that excerpt – however that means you can’t use the excerpt elsewhere on your site without making sure you add <p> wraps onto it like so <p><txp:excerpt /></p>. There are a couple of other easy methods to handle excerpts instead:

1. Install the etz_striptags plugin and wrap the excerpt like so:

<meta property="og:description" content="<txp:etz_striptags><txp:excerpt /></txp:etz_striptags>">

or…

2. Set up a custom field with an example name of ‘meta_description’ and use that field for your page description instead of using excerpt:

<meta property="og:description" content="<txp:custom_field name='meta_description' />">

The bonus is you could also utilise either of the two methods above to populate your <meta name="description"> tag, for example:

<meta name="description" content="<txp:etz_striptags><txp:excerpt /></txp:etz_striptags>">

or…

<meta name="description" content="<txp:custom_field name='meta_description' />">

Now the prep work has been done, you can now move on to adding Facebook features to your page. Add the code from here on into the article form you use to display individual articles.

Facebook ‘like’ button

The like button is now a hugely popular and recognised concept (whether we like it or not is highly debatable), here’s how to implement it…

<script>
  (function(){
  document.write('<p class="fblikethis"><fb:like href="<txp:permlink />" layout="button_count" width="100" show_faces="false"></fb:like></p>');
  var s = document.createElement('SCRIPT'), s1 = document.getElementsByTagName('SCRIPT')[0];
  s.type = 'text/javascript';
  s.async = true;
  s.src = 'http://connect.facebook.net/en_US/all.js#xfbml=1';
  s1.parentNode.insertBefore(s, s1);
  })();
</script>

You can add/change the attributes within the script (e.g. to add Facebook profile pictures) following this The implementation guide (attribute section).

Facebook ‘send’ button

Facebook recently provided a send button. Using this button users can send details about the page to their friends. You may prefer to use this button if you feel the context of liking a page is not in keeping with the philosophy/tone of that page content.

<script>
  (function(){
  document.write('<p class="fbsendthis"><fb:send href="<txp:permlink />"></fb:send></p>');
  var s = document.createElement('SCRIPT'), s1 = document.getElementsByTagName('SCRIPT')[0];
  s.type = 'text/javascript';
  s.async = true;
  s.src = 'http://connect.facebook.net/en_US/all.js#xfbml=1';
  s1.parentNode.insertBefore(s, s1);
  })();
</script>

You can add/change the attributes within the script following this implementation guide (attribute section).

Combined facebook ‘like’ and ‘send’ button

If you want both the above buttons together, use this code instead…

<script>
  (function(){
  document.write('<p class="fblikesendthis"><fb:like href="<txp:permlink />" layout="button_count" width="100" show_faces="false" send="true"></fb:like></p>');
  var s = document.createElement('SCRIPT'), s1 = document.getElementsByTagName('SCRIPT')[0];
  s.type = 'text/javascript';
  s.async = true;
  s.src = 'http://connect.facebook.net/en_US/all.js#xfbml=1';
  s1.parentNode.insertBefore(s, s1);
  })();
</script>

Facebook comments

Textpattern has very robust in-built comment features, but you may want to supplant that with the Facebook comments system instead.

Very easy to implement using the JavaScript asynchronous method:

<script>
  (function(){
  document.write('<p class="fbcomments"><fb:comments href="<txp:permlink />" width="480" num_posts="20"></fb:comments></p>');
  var s = document.createElement('SCRIPT'), s1 = document.getElementsByTagName('SCRIPT')[0];
  s.type = 'text/javascript';
  s.async = true;
  s.src = 'http://connect.facebook.net/en_US/all.js#xfbml=1';
  s1.parentNode.insertBefore(s, s1);
  })();
</script>

You can add/change the attributes within the script following this implementation guide (attribute section).

You may wish to moderate Facebook comments, if so, add the following line to your meta_sharing form…

<meta property="fb:admins" content="{YOUR_FACEBOOK_USER_ID}">

…or if you have lots of articles (recommended)…

<meta property="fb:app_id" content="{YOUR_APPLICATION_ID}">

…the second method allows you to moderate all comments from within your developer app page instead of directly moderating each comment using your personal Facebook account.

Other facebook plugins

Now that you should be familiar with the JavaScript functions above, you can easily use that method for adding any of other Facebook social plugins to your Textpattern articles.

Just amend the FBML tags in the script to that of your chosen plugin (for example fb:live-stream for the Live Stream plugin) and amend the attributes following each plugin’s guide and you should be able to quickly implement any Facebook plugin.

Bonus round: add a twitter ‘tweet’ button too!

You can use the concept above to also easily add a ‘Tweet’ button to your page, again it loads asynchronously so won’t delay your page from rendering and uses the Twitter JavaScript API.

Place the following code in your article form:

<script>
  (function(){
  document.write('<p class="tweetthis"><a href="http://twitter.com/share" class="twitter-share-button" data-url="<txp:permlink />" data-count="horizontal" data-via="{YOUR_TWITTER_USER_ID}">Tweet</a></p>');
  var s = document.createElement('SCRIPT'), s1 = document.getElementsByTagName('SCRIPT')[0];
  s.type = 'text/javascript';
  s.async = true;
  s.src = 'http://platform.twitter.com/widgets.js';
  s1.parentNode.insertBefore(s, s1);
  })();
</script>

Replace {YOUR_TWITTER_USER_ID} with your personal twitter account ID name. Done!

Now go and be sociable!

comments powered by Disqus