Raplets tutorial part 1 – ‘Hello World’

In this post we’ll actually start playing around with Raplets by making our first Raplet, the ‘Hello World’ Raplet. If you don’t know what Raplets are, then I suggest you read my previous post which will give you an introduction of Raplets.

Create a file ‘raplet.php’ with your favorite editor and save it in a folder of your choice in your root directory (I’m on a windows machine, so my root directory is ‘C:/wamp/www/’ and I’m naming my folder as ‘Raplet’). This is the main raplet file. It accepts the requests and (optionally calls out other functions/files for processing that data) sends the responses. Put the following in the file ‘raplet.php’:
[php]

//Parameters in the request from Rapportive to our Raplet
$callback = $_GET[‘callback’];

if(isset($_GET[‘name’]))
{
$name=$_GET[‘name’];
}
else
{
$name="";
}

if(isset($_GET[’email’]))
{
$email=$_GET[’email’];
}
else
{
$email="";
}

if(isset($_GET[‘twitter_username’]))
{
$twitter=$_GET[‘twitter_username’];
}
else
{
$twitter="Twitter account not found.";
}

//Our response
$parameters = array();
$parameters[‘html’] = "<p>Hello World.</p><p>".htmlentities($name)."</p><p>Email id:".htmlentities($email).".</p><p>Follow on Twitter: ".htmlentities($twitter)."</p>";
$parameters[‘css’] = "p{margin:0; padding:0; color:#444; font-size: 13px; }";
$parameters[‘status’] = 200;

//We encode our response as JSON and prepend the callback to it
$object = $callback."(".json_encode($parameters).")";
echo $object;

[/php]

Lets get to know the parameters in the code above:

1. callback: This is the most important parameter. Every request from Rapportive to our Raplet contains a ‘callback’. Its a random string which changes everytime a new request is sent to our Raplet but it remains the same throughout the code. It should be pre-pended to our response.
2. name: The name of the person whose information is requested. Suppose you are viewing an email form ‘rutwick@xyz.com’, then this parameter’s value will be ‘Rutwick’.
3. email: Email address of the person you are viewing. Here, it will be ‘rutwick@xyz.com’.
4. twitter_username: Twitter ID of the person in question. @rutwick in our case.

Another important parameter which we will be including later when we move on to making a configurable Raplet:

5. show: This is the second important parameter. ‘The show parameter allows Rapportive to specify what information should be returned’. A normal lookup operation omits this parameter, but it contains a value depending on what type of information is requested.

Our JSON encoded response to this request should contain the following:

1. html: This is the actual structure of our Raplet. It defines the display of our Raplet in the Gmail inbox sidebar. It should be an html string with PHP output inserted wherever needed.
2. css: This contains all the styles we need to apply to our Raplet. Note that ‘html’ parameter cannot contain ‘<style>’ tags, so all our styles should come over here.
3. status: This is HTTP status parameter. Lets keep it 200 for good sake! 😉

An important parameter we’ll be using later:

4. js: All the Javascript code we need. jQuery is supported by default, so we can even include jQuery code here. Just like the ‘<style>’ tags, ‘html’ cannot contain the ‘<script>’ tag, so all our scripts come here.

We encode these as a JSON object and echo the object. An important thing to remember: Neither our Raplet nor any of the functions we use for processing our data should echo/print out anything else but the final JSON encoded return object.

Wondering what now? We’re all set to install our Raplet in our Gmail inbox and see it in action!

Like I mentioned in the pre-requisites, Rapportive should be installed for the browser you use. Currently Rapportive is available for Mozilla Firefox, Safari, Chrome and Mailplane. If you haven’t installed it yet then you should go on to install it from Rapportive.com.

Follow the steps:

1. Start your local server. Beacuse we have our Raplet hosted locally, it won’t work if your server is off!
2. Log in to Gmail and you should be able to see the ‘Rapportive’ icon at the top of your page (where you have a couple of links along with the ‘Sign out’ link).
3. Hover over it and click on login. Follow the further login instructions.
4. Hover over it again and then click on ‘Add/Remove Raplets’. The Raplets page will open up.
5. You can see a list of currently available Raplets over here. Scroll to the bottom and you’ll see a blank Raplet that says ‘Custom Raplet’.
6. Click on the add button and a dialog box will open up. Enter the URL of the Raplet we just created. So it will be ‘http://localhost/<name of the directory your raplet file is in>/raplet.php’ for a Windows machine with Wamp server installed.
7. Enter the URL over here and if all went well (!), and if our JSON object is properly formed and fetched by Rapportive, then you’ll see our Raplet being listed on this page.
8. Alternatively, check on the right hand side of the Raplets page, you should see our Raplet’s URL over there in a box below the main Rapportive social status box (We’ll later put our preview image over here when we add a ‘metadata’ section to our Raplet.
9. Now open up an email in your Gmail inbox, and watch the show… The Rapportive social status box will load first and then our Raplet will load. You can see the string that we had set in our Raplet, with all the styles applied and the formatting we had set. So if you open up an email from rutwick, then our Raplet should show ‘Hello World. Rutwick Gangurde. Email: rutwick@xyz.com. Follow on Twitter: @rutweets’.
10. Thats it! You have your first Raplet up and running!

In the next post we’ll see how to make our Raplet configurable by adding a ‘metadata’ section and how to add jQuery to our Raplet to make it more dazzling!