A Guide to Raplets

April 14th, 2011 in PHP | Raplet Development

Here at Coding Futures we’ve been using Rapportive to gain extra information whilst in Gmail including Gmail for Apps.

Rapportive is a Firefox plugin or Chrome extension which replaces the right hand sidebar which normally has adverts with information about individuals, the person selected, depends on the email, normally it’s the person who sent the email, but it can be a person whose email has been highlighted within the email.

One of the great features of Rapportive is the ability to add your own custom Raplets. Raplets are widgets that appear next to your email under the default Rapportive information. There are already preconfigured Raplets provided by companies such as Mail Chimp and Lanyrd, and we have developed a simple one for Capsule CRM.

For this tutorial, however, we are going to concentrate on creating a simple Raplet which whilst won’t serve much in way of functionality, it should help set the foundation to building your own custom Raplet and allow you to see the possibilities.

Basic Raplet

Install Rapportive

The first step is to install Rapportive. Head to http://rapportive.com/ and click the button marked “Add Rapportive to Gmail”. I’m going to assume you’ve installed plugin for Firefox or Chrome before and can complete this without any further instruction.

Create the Raplet

Raplets work like this; Rapportive will make a request to your URL, including data such as the recipients email, twitter handle and various metadata you can supply, you then then do whatever you need to do with the data and send some back. All over JSONP. For this example, we’ll just be using the email supplied by Rapportive, but you should be able to see how you can use other information in a similar way (except for the metadata which requires more configuration, but we’ll post another article detailing that soon).

First we need to receive the data that Rapportive sends across. Because all we need is the email and callback parameter, this is relatively simple. Open up a new page in your favourite editor and paste this code in:

$callback = $_GET['callback'];
$email = $_GET['email'];

Now that we have these, let’s build our HTML response:

$html = '<h2>Raplet Example</h2>';
$html .= '<p>' . $email . '</p>';

Rapportive expects a response in this format:

jsonp123456789({
"html": "HTML content",
"css": "CSS content",
"js": "JS content",
"status": 200
})

So, (ignoring the CSS and JS content for now), lets build our callback:

$return = json_encode(array(
'html' => $html,
'status' => '200'
));
}
echo $callback . "(" . $return . ")";

The complete code should look like…

$callback = $_GET['callback'];
$email = $_GET['email'];
$html = '<h2>Raplet Example</h2>';
$html .= '<p>' . $email . '</p>';
$return = json_encode(array(
'html' => $html,
'status' => '200'
));
echo $callback . '(' . $return . ')';

Add the Raplet

Next, head to http://raplets.com (making sure you’re logged into Rapportive in Gmail), and scroll down to add a custom Raplet.

Click “add this”, and enter your URL when prompted. Rapportive will check the URL is valid, and if all goes as planned, add the Raplet to your sidebar.

Open up Gmail (you may have to reload the tab if you already had it open), click on an email, and you should see your Raplet displayed at the side! It does look a bit plain though doesn’t it…

Adding CSS and JavaScript

Luckily, adding CSS and javaScript is actually very simple. When passing back the html property, you just pass back css and js properties too.

Go back to your editor and add the highlighted lines to your existing code.

$callback = $_GET['callback'];
$email = $_GET['email'];
$html = '<h2>Raplet Example</h2>';
$html .= '<p>' . $email . '</p>';
$return = json_encode(array(
'html' => $html,
'css' => 'h2 { border-bottom:1px solid #CCC; } p { color:grey }',
'js' => 'alert("Raplet alert!")',
'status' => '200'
));
echo $callback . '(' . $return . ')';

Now go back to Gmail and refresh. You should see your alert and the new styles!

The possibilities…

This has only been a small taster into what Raplets are capable of; there is still a lot more we haven’t covered. For instance, here are some of the things we skipped:

  • jQuery interaction
  • Metadata
  • User Configuration
  • User Authorisation

Hopefully though, it’s given you some inspiration and shown how easy it is to create a Raplet of your own.

Keep an eye out for our follow up articles, which will focus on implementing metadata and user customisation/authorisation.

Authors

Todd Francis
Shortly after qualifying from Leeds Uni with a degree in New Media Todd became a professional coder. Soon after he caught the eyes of Tim and Kevin who were looking for a developer for their new company and he became Coding Future's first employee. Two days later he was in Rome talking to very large clients and things haven't slowed much since