Raplets tutorial part 1 – ‘Hello World’

31 Oct

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’:


//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;

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.
  5. Another important parameter which we will be including later when we move on to making a configurable Raplet:

  6. 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! ;)
  4. An important parameter we’ll be using later:

  5. 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!

7 Responses to “Raplets tutorial part 1 – ‘Hello World’”

  1. Martin Kleppmann November 1, 2010 at 10:07 am #

    Hi Rutwick, great series of posts! Thanks for writing up this tutorial :)

    Just a little improvement to your script above: to prevent cross-site scripting attacks (http://en.wikipedia.org/wiki/Cross-site_scripting), I recommend that you HTML-encode your strings before inserting them into the $parameters object, i.e.:

    $parameters['html'] = “Hello World.”. htmlentities($name).”Email id:”.htmlentities($email).”.Follow on Twitter: “.htmlentities($twitter).”";

    This is important because any Rapportive user may change their name to something like alert(‘hello!’) :)

    • Martin Kleppmann November 1, 2010 at 10:11 am #

      Uh, WordPress has stripped out the HTML in my example. Trying that again:

      $parameters['html'] = "<p>Hello World.</p><p>". htmlentities($name)."</p><p>Email id:".htmlentities($email).".</p><p>Follow on Twitter: ".htmlentities($twitter)."</p>";

      • Rutwick Gangurde November 1, 2010 at 11:11 am #

        Hi Martin,
        Thanks a lot! :)
        I have updated the example with all the strings html-encoded.
        I read about cross-site scripting on Wikipedia and realized I was pretty unaware about it. So now on I’ll html-encode all my output strings! :)

        Rutwick

  2. Hayee September 6, 2012 at 12:27 pm #

    Hi,
    I am new and I am having a issue when i add custom raplet i get this error “This link returned an invalid response, please check it is correct.”

    This is responce that i get from my local raplet.php

    ({“html”:”
    Hello World.

    Email id:.

    Follow on Twitter: Twitter account not found.”,”css”:”p{margin:0; padding:0; color:#444; font-size: 13px; }”,”status”:200})

    Can you please help me in this.
    Second that i want to have do we get raplet output on our local browser or it will directly go to gmail on rapportive.
    Regards
    Abid

    • rutwick September 7, 2012 at 6:40 am #

      Hi,
      You Raplet is probably outputting invalid JSON, hence you’re getting the error.
      When you install a Raplet successfully in your gmail, you have to open up an email to see the Raplet in action in the inbox sidebar.
      Let me know if this helps!
      - rutwick

Trackbacks and Pingbacks

  1. Raplets tutorial part 1 – ‘Hello World’ - January 13, 2011

    [...] what Raplets are, then I suggest you read my previous post which will give you an introduction… [full post] Rutwick Gangurde Rutwick Gangurde's Blog rapletssidebar apps 0 0 [...]

  2. Use Google App Engine to host a Rapportive Raplet | Rutwick Gangurde's Blog - March 1, 2011

    [...] Before you begin, make sure you meet the following prequisites: 1) A basic understanding of Rapportive Raplets. This article assumes that you know what a Rapportive Raplet is and have made atleast a simple ‘Hello World’ Raplet. If you need an intro on what Raplets are, please visit the Raplets website. Learn how to make a ‘Hello World’ Raplet using PHP. [...]

Leave a Reply