Trail Map: Creating and Hosting an Open Social Application on a Ringside Server.

Step 1. Log In

Log into your Ringside server as a registered user such as joe@goringside.net (default password is ringside).

Step 2. Goto the Developer App

Select the Developer application from the horizontal menu at the top of the page.

Step 3. Create a New Application

We will now define a new application. Select the link at the bottom of the page "Add New Application...". Name this application, "OS Hello World" and the press the create application button.

Step 4. Edit Your Application Properties

You will now see your new application's API and SECRET keys. These will be provided automatically to your OS application a runtime. Select the "Edit Application Properties" link at the bottom of the page to continue.

Step 5. Define Callback and Canvas URLs

Your application must now be provided with a Callback URL, a Canvas URL and an application display type.

Your Application's Callback URL is the page that will be displayed after the user logs into your server. We will be displaying an Open Social Gadget as your application. For simplicity we will used an existing Shindig script which will render the contain and the gadget for you. Enter the following as your callback url: http://localhost:8080/ringside/gadgets/ifr?url=http://localhost:8080/ringside/trail_map_8/rs_os_hello.xml. Please remember to change the port from 8080 to whatever port your ringside server is installed on.

Your application's canvas URL will be "oshello". This will make your application's URL at runtime on your ringside server http://localhost:8080/ringside/canvas.php/oshello.

Your application type must be set to "Use IFrame". This setting can be found right below the line where you entered your Canvas URL and is very important. Open Social Gadgets expect to be run inside their own IFrame. At runtime this IFrame will load its own Open Social Javascript container which will then load your gadget description XML document.

Select the "Save Changes Button" to continue.

Step 6. Creating a Gadget Definition Document.

You will now create a Gadget Definition Document. This is an XML document, in which you will write your social application. The source for your hello world OS gadget has been placed in the <Ringside install>/apps/ringside/trail_map_8 directory in a file called rs_os_hello_sample.xml. You may rename it or create your own. Your gadget definition should be called rs_os_hello.xml and be placed in this same directory.

Our document will have two parts. The first is a ModulePrefs XML block. This block is used to "include" standard javascript libraries provided by the container. In this example we will only require the opensocial-0.7 library.

apps/ringside/trail_map_8/rs_os_hello.xml

<?xml version="1.0" encoding="UTF-8"?>
<Module>
	<ModulePrefs title="hello world example">
		<Require feature="opensocial-0.7"/>
	</ModulePrefs>

The contents of this library will be available to our Javascript at runtime. Many other libraries are available to you and they can be found in the <install>/apps/ringside/shindig/features directory.

The second block in our definition will be the Content block. The contents of the content block represent HTML which will be inserted into your Gadget's IFrame when it is initialized. This is a great place to put and "Please wait" messages and to establish any HTML your gadget may want to manipulate with its javascript. You can include CSS references and any javascript you want to be run to establish your gadget. Since you want your gadget to execute after the entire IFrame has been loaded, most developers use the container command "gadgets.util.registerOnLoadHandler();" to register a Javascript function to run after loading is complete. Below is the text of the remainder of the gadget definition including the gadget's javascript for your review.

apps/ringside/trail_map_8/rs_os_hello.xml

<Content type="html" view="default">
	<![CDATA[
		<script>
			/**
			 * This function will be called when the container has gotten
			 * a response from the server from your two open social requests.
			 * It is responsible for rendering the HTML for displaying your name
			 * and the name of your friends.
			 */
			function onLoadFriends(data) {
				var viewer = data.get('viewer').getData();
				var viewerFriends = data.get('viewerFriends').getData();

  				document.getElementById('main').innerHTML = '<h2>Hello '+viewer.getDisplayName()+'</h2>';

				html = new Array();
				//html.push('<h2>Hello '+viewer.getDisplayName()+'</h2>');
				html.push('<ul>');
				viewerFriends.each(
					function(person) {
						var line="<li>" + person.getDisplayName() + " ";
						if(person.getField(opensocial.Person.Field.THUMBNAIL_URL)!=''){
							line=line+" <img src='"+person.getField(opensocial.Person.Field.THUMBNAIL_URL)+"'/>";
						}
						line=line+"</li>";
 						html.push(line);
 					}
 				);
  				html.push('</ul>');
  				document.getElementById('friends').innerHTML = html.join('');
			}

			/**
			 * This function creates a newDataRequest object which is
			 * a collection of multiple open social requests which will
			 * be executed in a single batch. The onLoadFriends function will
			 * be called when this information has been returned.
			 */
			function loadFriends() {
  				var req = opensocial.newDataRequest();

  				// If not in a ringside Iframe, redirect for authentication
  				opensocial.requiresLogin('5bcf83f48c7e3c7ebd2a5352642335af');

  				// Ask for this user's name and their friends in one request.
  				req.add(req.newFetchPersonRequest('VIEWER'), 'viewer');
  				req.add(req.newFetchPeopleRequest('VIEWER_FRIENDS'), 'viewerFriends');
  				req.send(onLoadFriends);
			}

			/**
			 * Init will be called when the gadget IFrame is completely loaded.
			 */
			function init() {
  				loadFriends();
			}

			gadgets.util.registerOnLoadHandler(init);

		</script>

<h1>Open Social Hello World Sample</h1>

<div id='main'>
</div>
	Your friends are:
	<div id='friends'></div>
]]>
	</Content>
</Module>

Step 7. Running Your Application

Now that your gadget definition is in place, you are ready to test out your gadget based application. While still logged in as a user, select "Applications" from the menu across the top of the page. Select the "+ Add New Applications" button. Click on the link to the right of "OS Hello World" named "Add this Application" then choose the "Add Application" button. This will add the application to your profile. You will no be looking at your running OS application which has been deployed to your Ringside server.