This trail assumes that you've just completed your installation, and starts from there. Throughout this trail, you will be creating a simple application called "Hello" that will make a simple API call via the Ringside client.

In order to create a Ringside application, the following steps must be executed:

1. Create your application
2. Configure your application
3. Deploy your application

Let's talk about each step in turn.

Some of these instructions, particularly those that reference URLs, assume you've installed the Ringside software via the installer. If you are using an advanced development environment, based on an SVN working copy, your URLs will be different. Specifically, you will need "web/" in your URLs when going to the Ringside web front end and "api/" when specifying the restserver.php.

1. Create Your Application

First, let's create a simple application. To do so, you will need to configure a reusable client and integrate it into your application.

Configure a Reusable Client

Your application will need to communicate with the Ringside server via the use of a client. To set up your application's client code, you first need to obtain the Ringside clients distribution (which is available as either a tarball or zip file).

To get a clients distribution, you can either download one from here (ringside-client-1.0.tar.gz or ringside-client-1.0.zip) or you can grab the latest-n-greatest from our Hudson build system. You can even build one yourself if you'd like. To build one yourself, make sure you have the latest Ringside code then go to the /build directory and execute phing -f build-clients. The client distributions will be stored in dist/clients/distro).

1. Unzip and untar it to [application_root]. This should result in a directory structure: [application_root]/ringside/api/clients.
   • [application_root] is a destination on your Apache Web Server (e.g. if your are using the Ringside Install, it should be [installation dir]\apps\ringside\htdocs\hello)
   • Unzipping and Untarring can be accomplished by this command on MacOS or linux: tar -zxvf ringside-client-1.0.tar.gz
2. Create a new file: [application_root]/config.php. It should look like this:

   <?php
   $api_key = 'CHANGEME';  
   $secret = 'CHANGEME';
   $server_url = 'http://localhost/restserver.php';
   ?>

3. You will need to replace the $api_key and $secret values in [application_root]/config.php with the ones you got from the Ringside Developer application (we'll walk you through this in the next section). Also, note that if your server is running on a different port than 80, you will need to update the value of $server_url accordingly (such as http://localhost:8080/restserver.php).

Integrate the client into your application

Now that your client is configured, your application can use it.

For this example, our "hello" application will be written in PHP and will be deployed within the same Apache web server as where the Ringside Application Server is deployed.

Our hello application's [application_root]/index.php would look like this:

<?php
// Facebook client has a debug setting that will emit a notice if not set
$GLOBALS['facebook_config']['debug']=0;

// RingsideApiClients is included in the Ringside clients distro you
// unpacked earlier; it defines some of your basic setup
include_once 'ringside/api/clients/RingsideApiClients.php';

// Include that config.php you created earlier, which defines the location of your
// Ringside REST server as well as your API and Secret key
include_once 'config.php';

// Setup our client so it can successfully talk to the Ringside Server's API
RingsideApiClientsConfig::$serverUrl = $server_url;
$client = new RingsideApiClients( $api_key, $secret );

// do our thing...
$client->require_frame();
$user = $client->require_login();
$name = $client->api_client->users_getInfo( $user, "first_name" );
echo '<p>Hello, ' . $name[0]['first_name']. '!</p>';
?>

In this example, a Ringside client has been created and used to retrieve the logged in user's first name for display. Also, you'll notice calls being made to require_frame() and require_login(). The require_frame() function ensures that this application page is displayed in an iframe or a canvas page (such that the top and left side navigation panels are certain to be displayed). The require_login() function ensures that the user is logged in by redirecting to the login page if the user is not currently logged in.

2. Configure Application

The Ringside Social Application Server needs to know about every application that it is hosting, in order to provide your application's services to users and other applications. Therefore, your application needs its own unique API key, and the Ringside server needs to know how to access the application.

Become a User

In order to get an API key, you first need to be a user of the system. You can log in as one of our sample users (joe@goringside.net/ringside) or create your own user by:

• Ensuring that your Ringside web server and database are running
• Directing your favorite web browser to http://localhost/ (or http://localhost:8080 if you already had another web server running on port 80 during your installation)
• Clicking the "Create a New Profile" link at the bottom of the screen

• Filling in your full name, E-Mail address, and desired password and click 'Sign Up!'

• Filling in the login form with the E-Mail address and password you just registered with and click the 'Login!' button

Get Your Keys

Now that you are a user of the system, you can get an API key. To do so:

1. Click the "Developer" link at the top of the page
2. Click "Add New Application"
3. Enter a name for your application (Use "hello" for our example application)
4. Click "Create Application"

At this point, you should see some output that looks like this:

These are the keys that your application will use. At this point you should go back to your application's config.php file and insert these keys in place of 'CHANGEME'.

Configure the application

Now that you've added an application, you will need to configure it. Click the link labeled 'Edit Application Properties' and modify the following fields:

• Icon URL: Ensure that the port number is correct (http://localhost/images/default-app.png or http://localhost:8080/images/default-app.png)
• Callback URL: http://localhost/hello/ (note that if your server is running on port 8080 the URL should be 'http://localhost:8080/hello/')
• Canvas URL: hello

Click the 'Save Changes' button to persist this configuration information. These settings let the Ringside Social Application Server know how to access the application.

3. Deploy Your Application

To deploy your newly created application, it needs to exist in your Apache Web Server's htdocs location. If you used the Ringside installer, this location is <installation dir>/apps/ringside/htdocs/. If you have already created this application in a 'hello' sub-directory in your Apache htdocs location, your application is already deployed and you can skip to the 'Add the Application' section below. If you have not deployed your application to Apache, you can make this happen via one of two approaches. First, you can copy the contents of your application to the appropriate location in the web server. To do so, copy [application_root] to <installation dir>/apps/ringside/htdocs/ or where ever your Apache Web Server's htdocs location is.

Alternatively, you can point the web server to the location of your application. To do so:

1. Open your Apache's httpd.conf file (e.g. <installation dir>/apache2/conf/httpd.conf
2. Add an alias to the directory of your application:

Alias /hello C:\ringside\workspace\hello 
<Directory "C:\ringside\workspace\hello">    
   AllowOverride None     
   Options None     
   Order allow,deny     
   Allow from all 
</Directory>

Change 'C:\ringside\workspace\hello' to the appropriate location on your machine.

Add the Application

Now that the application is deployed, you need to add it to your profile. To do so:

• Go to http://localhost/index.php and log in (or http://localhost:8080/index.php if you are running on port 8080)
• Click the 'Applications' link at the top of the page

• Click 'Add New Applications'

• Click 'Add this Application' for the 'Hello' application

• Click 'Add application!' (leave all check boxes on)

At this point, you should be directed to your application, which will simply display "Hello, <first name>" where <first name> is what you entered when you registered.