Version User Scope of changes
Dec 15 2009, 3:50 PM EST (current) steve
Feb 4 2009, 5:40 PM EST boe_wetpaint 8 words deleted

Changes

Key:  Additions   Deletions
This "Hello World" Tutorial describes the basic steps required to integrate Wetpaint Injected content into a website. (est. 10 minutes)

Note:
  • For a non-technical overview, visit the How it Works page on wetpaint.com

Specifically, this tutorial will walk you through the following steps:

  1. Retrieve "Hello World" content from the Wetpaint Injected API
  2. Display the "Hello World" content on your web page
  3. Add the Wetpaint Injected client library to your web page
  4. Enable the EasyEdit button
  5. Enable your users to edit and save the "Hello World" content

Step 1: Retrieve "Hello World" Content from the Wetpaint Injected API


Your server side pages can retrieve the "Hello World" content from the Wetpaint Injected API using a RESTful URL of the following format:


http://wapi.wetpaint.com/CellService/getCellContent.do?key=developerkey&ns=namespace&cell.cellId=cellname

This URL retrieves the "Hello World" content from the Wetpaint Injected API, providing it the following values:

  • Developer Key - a unique key provided when you are approved for Wetpaint Injected (e.g. "507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef")
  • Namespace - this is a unique name for your application, provided by Wetpaint when you are approved (e.g. "sandbox-trial")
  • Cell Name - this is the cell that contains the content that your users may edit. (e.g., "sample")
  • Cell.displayName - this is the name of the person who logged in to edit the wiki. (e.g., "testuser")
  • cell.url - this is the url to reference to the original page.

These values are working examples that you may use for test purposes. Get your own developer key today. The following is an example of the URL with working test values:


You can try this example by clicking on the RESTful URL and viewing the results in your web browser. View the page source to see the raw "Hello World" content that is returned from the Wetpaint Injected API. The content is contained within "<div>" tags to enable easy integration and formatting into your web page.

Step 2: Integrate Raw Content into Your Webpage


Place the content you retrieved from the Wetpaint Injected servers into your webpage where you want it to appear. For example you may output the content below the "<body>" tag as follows:

  • PHP:

<html>
<body>
<?php
$displayName = "TestUser";
$cellUrl = "mysite.com";
$ns = "sandbox-trial";
$cellName = "sample";
$key = "507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824e";
$url = "http://wapi.wetpaint.com/CellService/getCellContent.do?key=$key&ns=$ns&cell.cellId=$cellName&cell.displayName=$displayName&cell.url=$cellUrl";
$chandle = curl_init(); // Initialize a handle
curl_setopt($chandle, CURLOPT_URL, $url); //Set Url
curl_setopt($chandle, CURLOPT_RETURNTRANSFER, 1); //return results as String
$result = curl_exec($chandle); // execute the call
curl_close($chandle);
print $result;
?>
</body>
</html>


  • ASP.NET: Custom Server Control by Atilla Yadik at Webhun.com. You will find 2005 and 2008 version of the control. Enjoy.
<%@ Page Language="C#" %>
<script runat="server"> protected void Page_Load(object sender, EventArgs e)
public String renderWetpaintContent() {
Uri wpUrl = new Uri("http://wapi.wetpaint.com/CellService/getCellContent.do?key=507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef&ns=sandbox-trial&cell.cellId=sample&cell.displayName=testuser&cell.url=www.example.com&output=html");
System.Net.HttpWebRequest request = (System.Net.HttpWebRequest)System.Net.WebRequest.CreateDefault(wpUrl);
request.Method = "GET";
System.Net.HttpWebResponse response = (System.Net.HttpWebResponse)request.GetResponse();
System.IO.StreamReader reader = new System.IO.StreamReader(response.GetResponseStream());
return reader.ReadToEnd().ToString();
}
</script>
<html>
<body>
<%=renderWetpaintContent() %>
</body>
</html>

  • JSP:


<%@ page import="java.util.*" %>
<%@ page import="java.io.*" %>
<html>
<body>
<%

String developerKey = "507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef";
String namespace = "sandbox-trial";
String cellName = "sample";
String cellDisplayName = "Testuser";
String cellUrl = "http://www.example.com";
StringBuffer urlString = new StringBuffer("http://wapi.wetpaint.com/CellService/getCellContent.do?");
urlString.append("key="+developerKey);
urlString.append("&ns="+namespace);
urlString.append("&cell.cellId="+cellName);
urlString.append("&cell.displayName="+cellDisplayName);
urlString.append("&cell.url="+cellUrl);
URL url = new URL(urlString.toString());

HttpURLConnection connection = (HttpURLConnection)url.openConnection();
connection.setRequestMethod("GET");
connection.setDoInput(true);
connection.setDoOutput(false);
connection.setUseCaches(false);

InputStream istrm = connection.getInputStream();
ByteArrayOutputStream bstrm = new ByteArrayOutputStream();
int ch;

while ((ch = istrm.read()) != -1) {
bstrm.write(ch);
}

String s = new String(bstrm.toByteArray());
bstrm.close();
out.println(s.toString());
%>
</body>
</html>

The examples above return raw "Hello World" HTML from the Wetpaint Injected API and renders it into a web page, providing SEO benefits (see "before" image below).


Step 3: Add the Wetpaint Injected Client Library


The Wetpaint Injected client includes libraries of code that provide tools to enable your users edit the content. It also includes a stylesheet that provides formatting. To add the client to your webpage, include the following script tag in the Head section of your HTML:

<html>
<head>
<script src="http://wapi.wetpaint.com/JavaScriptService/getBootstrap.do?key=<your developer key>" type="text/javascript"></script>
</head>
<body>
...

After adding the script code, your webpage now includes Wetpaint Injected client controls instead of text (e.g. the EasyEdit button and the "What's this?" link):



Before adding script code to your web pageAfter adding script code to your web page

Web page Before and After Client is Added



Step 4: Enable the EasyEdit Button


To enable visitors to view the "Hello World" content, you need not do anything. But to enable visitors to edit the content, you need to enable the Wetpaint Injected EasyEdit button and require your visitors to login.

If your visitor is not logged in, you need to enable the EasyEdit button and direct the user to login. To enable the EasyEdit button, you will need to add the following script section to the Head section of your HTML:

<html>
<head>
<script src="http://wapi.wetpaint.com/JavaScriptService/getBootstrap.do?key=<your developer key>" type="text/javascript"></script>
<script type="text/javascript">
if( window.WPCAPI ) {
WPCAPI.setDeveloperKey("507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef");
WPCAPI.setNamespace("sandbox-trial");
WPCAPI.processLogin = function() { location.href = "/path/to/login/page.htm"; }
}
</script>
</head>
<body>
...


This authentication script sets the following Wetpaint Client (WPCAPI) properties:

  • Developer Key - same as before (e.g. "507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef")
  • Namespace - same as before (e.g. "sandbox-trial")
  • ProcessLogin - this is the URL to your login page (e.g. "/path/to/login/page.htm")

Note:
  • This is the same developer key and namespace that were used in Step 1.



Login Button

The Please Login Dialog Box



Now, when the user clicks the EasyEdit button, the Please Login dialog box appears.

Step 5: Enable your users to Login and Edit the "Hello World" content


After clicking the Login button, your user will be directed to the login page you specified in the processLogin property. You handle the user login as you normally do on your site, except, once the user successfully logs in, your server needs to use the Wetpaint Injected UserService API to obtain a Login Ticket on behalf of the user. This Login Ticket is used by the Wetpaint Client to enable the user to save their edits.

You may obtain a Login Ticket from the Wetpaing Injected UserServer API using the following:

  • PHP:
<html>
<body>
<?php
$userId = 'UserId';
$displayName = 'TestUser';
$email = "test@email.com";
$key = '507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef';
$secret = "yoursecretkey";
$ns = 'yournamespace';
$ts = time();
$sig_data = $key . $displayName . $ts;
$sig = hash_hmac( "sha1", $sig_data, $secret, FALSE );
$url = "http://wapi.wetpaint.com/UserService/login.do";
$post_fields.= "key=$key";
$post_fields.= "&ns=$ns";
$post_fields.= "&output=api";
$post_fields.= "&cred.ts=$ts";
$post_fields.= "&cred.sig=$sig";
$post_fields.= "&user.userId=$userId";
$post_fields.= "&user.displayName=$displayName";
$post_fields.= "&user.email=" .htmlentities($email);
$post_fields.= "&user.emailOptIn=true";
$post_fields.= "&user.profileUrl=";
$post_fields.= "&user.role=moderator";
$chandle = curl_init(); // Initialize a handle
curl_setopt($chandle, CURLOPT_URL, $url); //Set Url
curl_setopt($chandle, CURLOPT_POST, 1); //Send as POST
curl_setopt($chandle, CURLOPT_POSTFIELDS, $post_fields); //POST Fields with Values
curl_setopt($chandle, CURLOPT_RETURNTRANSFER, 1); //return results as String
$result = curl_exec($chandle); // execute the call
curl_close($chandle);
if( preg_match( "/<ticket>(.*)<\/ticket>/", $result, $match_array ) == 1 ) { //Get ticket value
$wetpaint_ticket = $match_array[1];
$ticket = $match_array[1];
//setcookie("wetpaint-togo",$ticket, time()+3600*12 ); // Probably you will save value in cookie
}
?>
</body>
</html>

  • Asp.Net:
using System;
using System.Collections.Generic;
using System.Linq; using System.Web;

public static class LoginManager
{
public LoginManger()
{

// // TODO: Add constructor logic here // }

public static String EnsureLoginWP(string userID, string userName, string userDisplayName, string userUrl, bool userEmailOptIn, string userEmail, string cellId)
{
//requirentments
string url = "http://wapi.wetpaint.com/UserService/login.do";
Uri uri = new Uri(url);
string developerKey = "507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef";
string developerSecret = "yoursecretkey";
string ns = "yournamespace";

//session
System.Web.HttpContext context = System.Web.HttpContext.Current;

//ticket variable holds the return ticket value
string ticket;

TimeSpan ts = (DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0));
long unixTime = (long)ts.TotalSeconds;
System.Text.UTF8Encoding encoding = new System.Text.UTF8Encoding();
String sigString = developerKey + userID + unixTime;
System.Security.Cryptography.HMACSHA1 hmacSha = new System.Security.Cryptography.HMACSHA1(encoding.GetBytes(wetPaint.DeveloperSecret));
byte[] sigHash = hmacSha.ComputeHash(encoding.GetBytes(sigString));
//byte[] sigHash = sha.ComputeHash(encoding.GetBytes(sigString));

string encodedSigString = GetAsHexaDecimal(sigHash);

string data = "key=" + developerKey + "&ns=" + ns + "&output=api&user.userId=" +
userID + "&user.email=" + userEmail + "&user.emailOptIn=" +
userEmailOptIn + "&cred.ts=" + unixTime + "&cred.sig=" + encodedSigString +
"&user.profileUrl=" + userUrl + "&user.displayName=" + userDisplayName;
string encodedData = System.Web.HttpUtility.UrlEncode(data);
System.Net.HttpWebRequest request = (System.Net.HttpWebRequest)System.Net.WebRequest.CreateDefault(uri);
request.ContentType = "application/x-www-form-urlencoded";
request.Method = "POST";
request.ContentLength = data.Length;


System.IO.StreamWriter writer = new System.IO.StreamWriter(request.GetRequestStream());
writer.Write(data);
writer.Close();

System.Net.HttpWebResponse response = (System.Net.HttpWebResponse)request.GetResponse();
System.IO.StreamReader reader = new System.IO.StreamReader(response.GetResponseStream());
string responseString = reader.ReadToEnd();

if (!responseString.Contains("<ticket>"))
{
//throw an exception }
else
{
String[] tokens = { "<ticket>", "</ticket>" };
String[] splits = responseString.Split(tokens, StringSplitOptions.RemoveEmptyEntries);
ticket = splits[1];
context.Session["WetpaintTicket"] = ticket; }

return ticket; }
public static string GetAsHexaDecimal(byte[] bytes)
{
System.Text.
StringBuilder s = new System.Text.StringBuilder();
int length = bytes.Length;
for (int n = 0; n < length; n++)
{
s.Append(
String.Format("{0,2:x}", bytes[n]).Replace(" ", "0")); }

return s.ToString(); } }


  • JSP


<%@ page import="java.net.*" %>
<%@ page import="java.util.*" %>
<%@ page import="java.io.*" %>
<html>
<body>
<%
if (request != null) {
String username = request.getParameter("username");
URL url = new URL("http://wapi.wetpaint.com/UserService/login.do");
String developerKey = "507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef";
long ts = Calendar.getInstance().getTime().getTime() / 1000L;

HttpURLConnection connection = (HttpURLConnection)url.openConnection();
connection.setRequestMethod("POST");
connection.setDoInput(true);
connection.setDoOutput(true);
connection.setUseCaches(false);

String sigString = developerKey + username + ts;
SecretKeySpec signingKey = new SecretKeySpec( "secret".getBytes( "UTF-8" ), "HmacSHA1" );
String sigHashString = null;
try {
Mac mac = Mac.getInstance( "HmacSHA1" );
mac.init( signingKey );
byte[] hash = mac.doFinal( sigString.getBytes( "UTF-8" ) );
sigHashString = new String( Hex.encodeHex( hash ) );
} catch ( NoSuchAlgorithmException e ) {
out.println(e.getMessage());
} catch ( InvalidKeyException e ) {
out.println(e.getMessage());
}

StringBuffer requestData = new StringBuffer();
requestData.append("key=");
requestData.append(developerKey);
requestData.append("&ns=");
requestData.append("sandbox-trial");
requestData.append("&cred.ts=");
requestData.append(Long.toString(ts));
requestData.append("&cred.sig=");
requestData.append(sigHashString);
requestData.append("&user.email=");
requestData.append("test@test.com");
requestData.append("&user.emailOptIn=false");
requestData.append("&output=api");

URL url = new URL( sbUrl.toString() );
URLConnection conn = url.openConnection();

conn.setDoOutput( true );

OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
String data = sbData.toString();
wr.write( data );
wr.flush();

BufferedReader rd = new BufferedReader( new InputStreamReader( conn.getInputStream() ) );
StringBuffer htmlBuilder = new StringBuffer();
String line;
while ( ( line = rd.readLine() ) != null) {
htmlBuilder.append( line );
}

rd.close();
String ticket = htmlBuilder.toString().split( "<ticket>" )[1].split( "</ticket>" )[0];

}

%>
</body>
</html>

The example(s) above return the the Login Ticket which is used in the JavaScript code below.

Place the Login Ticket you retrieved from the UserService API into your setLoginTicket HTML code. For example you may output the Login Ticket value into the HTML page so it can be used by the WPCAPI.setLoginTicket to enable the logged in user to edit the "Hello World" content. The the following script includes the addition of the WPCAPI.setLoginTicket line of script in the Head section of your HTML

<html>
<head>
<script src="http://wapi.wetpaint.com/JavaScriptService/getBootstrap.do?key=<your developer key>" type="text/javascript"></script>
<script type="text/javascript">
if( window.WPCAPI ) {
WPCAPI.setDeveloperKey("507ace0d168024cbcb53a9add0e6fe4e9796012e6b420cfafabac6a4357824ef");
WPCAPI.setNamespace("sandbox-trial");
WPCAPI.processLogin = function() { location.href = "/path/to/login/page.htm"; }
WPCAPI.setLoginTicket("your-login-ticket"); // only required if user is logged in
}
</script>
</head>
<body>
...



Once this fifth step is completed, your users will be able to view, login and edit the "Hello World" content.

Step 6:


Click the Get Injected button to Sign-up for a Developer Key so you can integrate Wetpaint Injected into your own website.

Hello World Tutorial Home - Hello World Tutorial