Raplets tutorial part 3 – Add metadata section to your Raplet

It’s time we make our Raplet configurable for everyone who wants to use it! Precisely, we are making it ready to be personalized… Not clear yet? Say we are making a Raplet for XYZ API which provides its users an API key for accessing the data. With a metadata section, users of our Raplet will be able to use their API key with our Raplet and hence access their data through the Raplet. And most important, the metadata section allows us to give our Raplet a firm identification by giving it a name, description, a logo etc. This information is also used when our Raplet is configured by Rapportive.

This article is the 4th in the Raplet development tutorial series. I assume that you have read the previous articles in the series and already have the Raplet we made along. If you haven’t, then I recommend you read all of them and follow them before continuing with this article.
Here’s the list of my previous articles in this series:

1. Building Raplets – Get started from here!
2. Raplets tutorial part 1 – ‘Hello World’
3. Raplets tutorial part 2 – Add JavaScript to your Raplet

Lets continue further…

In the 2nd post which we wrote our ‘Hello World’ Raplet, I had explained the parameters that Rapportive sends in a GET request to our Raplet. Here’s a quick glimpse of those parameters:

• callback
• name
• email
• twitter_username

These are the ones we have used till now in our Raplet. Now we are going to use the 2nd most important parameter, the ‘show’ parameter. Like I mentioned earlier, the ‘show’ parameter allows Rapportive to specify what information should be returned by our Raplet. Our Raplet was performing the normal look-up action till now and hence we did not use the ‘show’ parameter yet as it is omitted in a normal look-up action. Now when we want to add a ‘metadata’ section to our Raplet, we have to handle the ‘show’ parameter.
When our Raplet is being configured by Rapportive, it sends 2 parameters to our Raplet, ‘callback’ and ‘show’. The ‘callback’ is the random string used for request response matching, and the ‘show’ parameter has a value ‘metadata’. Read it as, ‘show me the metadata’!

Now its time for action, not words! \m/,

Open up our ‘raplet.php’ file. And modify the code to add the ‘metadata’ section as follows:
[php]

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

//Check if the ‘show’ parameter is set, and is set to ‘metadata’
if(isset($_GET[‘show’]) && $_GET[‘show’] === ‘metadata’)
{
//Yes, ‘show’ is set to ‘metadata’
// ‘metadata’ section starts here

$parameters[‘name’] = "Hello World!";
$parameters[‘description’] = "Add metadata to your Raplet.";
$parameters[‘welcome_text’] = "<p>Raplets are kewl!</p>";
$parameters[‘icon_url’] = "http://localhost/Raplet/raplet_icon.png";
$parameters[‘preview_url’] = "http://localhost/Raplet/raplet_preview.png";
$parameters[‘provider_name’] = "Rutwick";
$parameters[‘provider_url’] = "http://www.rutwickgangurde.wordpress.com/";
$parameters[‘data_provider_name’] = "The Internet";
$parameters[‘data_provider_url’] = "http://www.google.com";
$parameters[‘configuration’] = array(
array(
"name" =>; "firstname",
"type" =>; "text",
"description" =>; "Your Name:",
"required" =>; true
)
);

$object = $callback."(".json_encode($parameters).")";
}
else
{
//Nope. ‘show’ parameter absent, hence, look-up in progress

if(isset($_GET[‘name’]))
{
$name=$_GET[‘name’];
}
else
{
$name="What’s in a name?";
}

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

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

//The parameter we asked the user to enter when installing our Raplet. We had configured it in our ‘metadata’ section above.

$firstname = $_GET[‘firstname’];

//Our response
$parameters[‘html’] = "<p class=’head’>".htmlentities($firstname)." says, Click me!</p><div class=’info’><p>".htmlentities($name)."</p><p>Email id:".htmlentities($email).".</p><p>Follow on Twitter: ".htmlentities($twitter)."</p></div>";
$parameters[‘css’] = "p{margin:0; padding:0;} p.head{padding:2px 8px; cursor: pointer; position: relative; background- color:#eee; font-size:13px; border-bottom:1px dashed #bbb; font-weight:bold;} div.info{ padding: 5px 10px 15px; background-color:#F4F4F8; color:#444; font-size: 13px; }";
$parameters[‘js’] = "$(‘div.info’).hide(); $(‘p.head’).click(function(){ $(this).next(‘div.info’).slideToggle(600);});";
$parameters[‘status’] = 200;

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

echo $object;

[/php]
The code reads like this: If the ‘show’ parameter is set and if it has the value ‘metadata’, then conclude its an install operation and render the metadata section, else conclude that its a look-up operation (‘show’ is absent!) render the default section. This check is very important as it decides what action to take and when to take it. If the ‘show’ parameter is not set and/or is equal to a blank, then our code should ignore it.

The parameters in the ‘metadata’ section are as follows:

1. name: This is the name of our Raplet. It will be displayed on the Raplets listing page as well. We name out Raplet as ‘Hello World!’
2. description: A small description of our Raplet. Maximum 100 words only. We can use text formatting html tags such as italic tag, bold/strong tag or underline tag. But CANNOT use block level tags (p, div etc.).
3. welcome_text: Here we can put a few more lines of text that describe our Raplet, and instruct users on how to install it and what values are to be entered etc. We can use html here. On the Raplet listing page, when we select a Raplet and click on ‘Add this’, the value for ‘welcome_text’ shows up in a dialog box.
4. icon_url: This is the location of the icon we want to use for our Raplet. It has to be an absolute URL. For our Raplet, the icon_url is ‘http://localhost/<name of the directory your Raplet is in>/raplet_icon.png’. The icon should be 100×100 pixels in size, with a transparent background and no borders. Use .png, .gif or .jpeg images.
5. preview_url: This is the location of the preview image of our Raplet. This too should be the absolute URL, in our case, ‘http://localhost/<name of the directory your Raplet is in>/raplet_preview.png’. On the Raplets listing page, the preview image of the Raplet we install shows up below the preview image of the Rapportive social status sidebar. The preview image should be 220 pixels wide and height can be anything that looks good (!) with a white background. .png, .jpeg or .gif recommended.
6. provider_name:Who made this Raplet? Your name here fellas!
7. provider_url: The URL of the Raplet maker’s website. We can post some information about our Raplet on this website so that user can read it for details about the Raplet. If you have a website or a blog or a webpage that tells people about your ‘Raplet’ adventure ( 😉 ), enter its address here.
8. data_provider_name: If we are using data from a third party API for displaying in our Raplet, then we mention its name over here. Suppose you are using Twitter API, then this will be ‘Twitter’. This parameter is optional.
9. data_provider_url: The data provider’s website. Example: http://apiwiki.twitter.com/ (For the above scenario). This parameter too is optional.
10. configuration: Though this section is optional, we will need it if we want the users of the Raplet to enter some information in order to use the Raplet. An API key, for example.

The configuration section has 4 sub parameters. They are:

• name: The name of the configuration/input parameter we want the user to enter. Use alphanumeric and underscore characters.
  In our Raplet, its ‘firstname’. This parameter is sent by Rapportive to our Raplet in every look-up request after our Raplet is properly configured and installed. We code our Raplet in such a way that we can use this parameter for processing information.
• description: This is the description of the configuration/input parameter. Its the label of our config parameter.
• type: Type of the input control we want to use for taking the user input. Available types are: Text (corresponds to html input type ‘text’) and Password (corresponds to html input type ‘password’ and its input is masked).
• required: This specifies whether or not the input fields can be left blank. The values should be boolean ‘True’ or ‘False’. If true, the user cannot leave the field blank. It’s like a validation check!

The configuration section is transformed to a dialog box with our input fields in it. The user entered input is captured by Rapportive on our behalf.
The above set of properties form the ‘metadata’ section of our Raplet. Now when you or a user installs our Raplet from the Raplets listing page, it will ask you to enter the ‘firstname’ (with ‘Your name:’ as the label) and then install the Raplet. After installing the Raplet, you should be able to see our Raplet on the Raplets listing page with the information we specified in the metadata section along with the icon we provided. The preview image will be seen in the sidebar on the right hand side of the Raplets listing page.

Now our Raplet has an identity so that people can refer to it by that name. And the configuration section will allow people to personalize our Raplet for their usage.

After going through these tutorials, I’m sure you are able to write your own fully functional and configurable Raplet. For the entire details about Raplet development, I insist you Request the official Documentation from Rapportive. So look for an API, churn out an awesome idea and write your own Raplet to help people maximize their Gmail experience and possibly help them in expanding their business and social outreach!

In the next mini article in this series, I will write about debugging your Raplet code. There are a few things which if not taken care of, might cause your Raplet to behave in a strange way or worse, not let it install at all! I’ll pin point a few checks you should follow while developing your Raplet.