Theme of this Trail
What if you want to socially-enable an application that is running on a website that is completely separate from Facebook or even Ringside?
This trail will show you how to display your Ringside application on any web site, even in simple html documents independent of what server side scripting they might use.

Introduction

In the previous trail, you reduced all the functionality of your application into a simple set of fbml tags. These tags were:

<rs:suggestions showform="true"
                newtopics="true"
                existingtopics="false"
                topic="Great Band Names">
    <rs:ratings style="yesno"/>
</rs:suggestions>

For these tags to be displayed, you had to create an application and register its canvas URL. It could then be rendered and displayed inside your Ringside server or on Facebook. This trailmap will show you how to create an FBML rendering canvas anywhere on the web that can display your application inside any HTML document requiring only a web browser that support javascript.

A Simple Example

The ringside installation comes with some simple widget examples. The code discussed in this trail map can be found at:

<installation directory>/apps/ringside/htdocs/trail_map_7/

Step 1. Create simple.html

Create an empty html document in the trail_map_7 directory called simple.html (or copy and rename simple-sample.html).

Step 2. Paste the following html into this document.

<html>
<script src="http://localhost:8080/rswidget.js"  type="text/javascript" />
	<head>
		<title>Ringside Widget Demo</title>
	</head>
	<body onLoad="rswidget.renderAllWidgets('4333592132647f39255bb066151a2099');">
		<h1>Ringside Widget Demo</h1>
		<p>A Ringside Widget can be used to display embedded FBML documents rendered in the context and permissions of your application.</p>
		<p>Below is an example widget:</p>
		<div id="sample1" class="rs-fbml" style="border: 1px dashed gray; width: 633px; height: 200px; padding: 3px; background: lightyellow">
			<fb:success>
				<fb:message>This is the heading text for the message.</fb:message>
			</fb:success>
		</div>
	</body>
</html>

Step 3. Make sure the port is correct.

Review the code you have pasted into sample.html. Make sure that the port for the script tag matches your web server. http://localhost:8080/rswidget.js will work for unix but http://localhost:80/rswidget.js is required for windows.

Step 4. View the Rendered Results

Using your web browser, now view this document at http://localhost:8080/trail_map_7/simple.html under Unix or http://localhost:80/trail_map_7/simple.html under Windows.

Step 5. Your Results

If everything is successful, you will see output like the figure below:

How It Works

The Ringside rswidget scans your document for all html div blocks of the class rs-fbml. When it finds one, it treats it as if it were a canvas for whatever application it was initialized with. In this case use used rswidget.renderAllWidgets('4333592132647f39255bb066151a2099') which happens to be the api_key for the pre-installed Footprint application.

Any FBML present in inside the div tag is treated as FBML and sent back the the ringside server to be rendered as if it was running as the Footprints application. Another important question to understand is which user is this widget running as? In this simple example you are running as an anonymous user. This means that any tags used that must know who the current users are will fail. This is why fb:message was used in this example, since it does not require a user to render its results.

Running Logged in as a User When Displaying a Widget

Step 1. Creating user.html

For your widget to have a social context (knowing who is logged in and who their friends are) someone must be made to log in when it is displayed.
The example below can be used following the steps above to create user.html in the same way you created simple.xml.

<html>
  <script src="http://localhost:8080/rswidget.js"  type="text/javascript" />
  <head>
	<title>Ringside Authenticated Widget Demo</title>
  </head>
  <body onLoad="rswidget.renderAllWidgets({apiKey:'cecdc629adb83f81236ba9342ce68492',
		loginServer:'http://localhost:8080',
		forceAuthentication:true,
		renderEndpoint:'http://localhost:8080/render.php',
		trustEndpoint:'http://localhost:8080/trust.php'
		});">
	<h1>Ringside Widget Demo</h1>
	<p>A Ringside Widget can be used to display embedded FBML documents rendered in the context and permissions of your application.</p>
	<p>Below is an example widget:</p>
        <div id="sample1" class="rs-fbml" style="border: 1px dashed gray; width: 633px; height: 200px; padding: 3px; background: lightyellow">
		It is a picture of <fb:name uid="100001"> <fb:profile-pic uid="100000" size="square" linked="true"><p>
	</div>
</html>

Step 2. Creating an Application for user.html

Because user.html contains a widget that expects the view to be logged in we must create a new application for it. This application will have the following settings. Follow the procedure from the previous trails to see how to create a new application.

Name: trail7_users
API Key: cecdc629adb83f81236ba9342ce68492
Secret Key: dc948ea1d21917d9d726d9f8f69eb532
Callback URL: http://localhost:8080/trust.php  (Note: Change port to 80 for Windows)
Application Type: FBML

Step 3 Running user.html

Once you have created your application inside your Ringside server it can be viewed at http://localhost:80/trail_map_7/user.html and should look like the figure below.

How it Works

Since this widget is going to display a fb:profile-pic it will need to know who is viewing this page and to do that it must force your to log in. Here we have expanded the options used in the renderAllWidgets command to include a loginServer:, trustEndpoint: and forceAuthentication:true. This will force the HTML page to re-direct to a login page which will then re-direct the the trust.php page which will establish a session for you. Trust will then re-direct back to the original widget page with additional URL query parameters the widget will use to make calls as a particular user. Here is a diagram which shows more details on how this process works. This digagram assumes you are using facebook as your login server, unlike this example which uses ringside for both authentication and FBML rendering.