Creating a 'Hello World' Sproutcore application for OpenSocial

This tutorial could also be titled: How to turn a Sproutcore application into an OpenSocial application. We will run through writing a Hello World OpenSocial application using SproutCore. We will start from the basics of installing sproutcore before teaching you how to create a sproutcore application and turning it into an OpenSocial application. Finally, we'll finish by showing you how to deploy the application on your web server.

Installing Sproutcore

In this tutorial, we will be using the latest stable release of sproutcore, which we will install using Rubygems. In order to use sproutcore, you will need to install Ruby and Rubygems into your system. I suggest you use RVM to install Ruby. That way you can run multiple instances of Ruby on your machine and switch between them very easily. RVM is very easy to install. Just follow the instructions on their site. For running sproutcore, I recommend you use ruby version 1.8.7 or 1.9.1.

Once you've installed RVM, you can see a list of ruby versions on your machine by using:

rvm list
When I run this on my machine, I see the following:
rvm rubies

=> ruby-1.8.7-p302 [ i386 ]
   ruby-1.8.6-p399 [ i386 ]
   ruby-1.9.1-p378 [ i386 ]
The arrow points to ruby-1.8.7 which is the version I'm using. If I wanted to switch to Ruby 1.9.1, I would type:
rvm use ruby-1.9.1-p378

Once you've installed ruby and rubygems with RVM, switch to version 1.8.7 or 1.9.1 and you are ready to install sproutcore. All it takes is one command:

sudo gem install sproutcore

Creating and testing the Hello World application

The first application we will create is very simple. It's just a Hello World application and in fact, Sproutcore ships with a set of generators that creates a hello world application by default for you. So all we will do in terms of Sproutcore in this tutorial is run the generator, launch the server, and see the results in a browser. We realize this is not super exciting but we want the focus of this tutorial to be on what you need to do to turn a sproutcore application into an OpenSocial application. We will post more interesting Sproutcore tutorials in the near future so that you can learn more about Sproutcore.

We are going to call this application HelloSprouts. To generate it, simply open a shell in the directory where you want to save the application and type:

sc-init HelloSprouts

Just by running this, sproutcore created a hello_sprouts directory with the right sub-directories and the code needed for the most basic sproutcore application. Let's see what it looks like:

cd hello_sprouts
sc-server

You can now fire up your browser and point it to http://localhost:4020/hello_sprouts.

You should see the following:

Hello Sprouts Screenshot

Congrats!

It wasn't too hard, but you got your first SproutCore application running. Let's learn how to deploy it to a server first, and then we'll see how to turn it into an OpenSocial application.

Deploying the application

We will describe how to deploy the application to a server running nginx. If you are using Apache or another web server, it shouldn't be too hard to figure out how to adapt these instructions to work for your server. A SproutCore application is a static HTML/JavaScript application so deploying it is very simple.

The first step is to build the application. Sproutcore ships with a tool that does that for us. Open your shell in the hello_sprouts directory and type:

sc-build

Sproutcore will start building your application as soon as you hit the enter key. It will take a few seconds/minutes. When it's done, you will notice a new tmp/ directory. Inside that directory, there should be a build/ directory. Inside that build/ directory is the static directory where you will find the code for your application. That is the one you need to serve with your web server.

On your web server, create a directory for your new application under your WWW_ROOT directory. In my case I call this directory hello_sprouts/ and keep it under ~/www/. So SSH into your server and create it:

cd ~/www
mkdir hello_sprouts
ln -s . static

The last symlink created here is important! Do not forget it or else your browser will not be able to find the files on your webserver.

Then back on your developer machine (in my case my laptop), go to the root directory of your application and package the files into a .tar.gz archive:

cd tmp/build/static && tar -cvpzf static.tar.gz hello_sprouts/ sproutcore/

This should have created a file called static.tar.gz into your tmp/build/static directory. Let's move it to the server (make sure you replace yourusername and yourhostname.com):

scp tmp/build/static/static.tar.gz yourusername@yourhostname.com:~/www/hello_sprouts/

Once that archive is on your server, ssh back into your server and into the ~/www/hello_sprouts directory and untar the file:

cd ~/www/hello_sprouts
tar xzvf static.tar.gz
rm static.tar.gz

You should now have two directories in your hello_sprouts directory: the sproutcore directory which holds the sproutcore frameworks and the hello_sprouts directory with the content of your application. In order for your webserver to serve the application, you need to create a symlink for index.html. Note that sproutcore creates a directory name with a unique UUID so your command will differ from mine a bit:

cd ~/www/hello_sprouts/
ln -s ~/www/hello_spouts/hello_sprouts/en/01f4635878639aac0383bea600aaf117e78bd15a/index.html index.html

You now have all your files in place. What's left is to configure your web server to serve the files in this directory. We are going to serve the files on port 8090 of our webserver so make sure you have this port open first, and then configure nginx to serve the files on this port. An example nginx config can be seen below:

    server {
        listen 8084;
        server_name yourhostname.com;
        root /home/yourusername/www/hello_sprouts;
    }

Restart nginx and try load your application from yourhostname.com:8090.

Turning the application into an OpenSocial application

There are a few things we need to do to turn this application into an OpenSocial application.

Makes resources relative

Open the Buildfile in the root directory of your Sproutcore application and replace this line:

config :all, :required => :sproutcore

... with this:

config :all, :required => :sproutcore do |c|
  c[:resources_relative] = true
  c[:url_prefix] = 'http://groupdock.com:8090'
end

Create layout for OpenSocial XML Specifications

An OpenSocial application is defined by its XML Specification file (also see the GroupDock specific XML Specs requirement).

Right now, our HelloSprouts application serves straight HTML. We need to convert that so that it sends the XML Specifications instead. We can do that by creating our own layout (similar to a RAILS layout if you are familiar with that) to replace the Sproutcore default layout.

To do this, first we need to create the file, then we'll tell Sproutcore that it should use the file. Create a file called index.rhtml in the hello_sprouts/apps/hello_sprouts/ directory. This file is an erb template. If you come from a Ruby/Rails background you should be familiar with these. Otherwise, you should be OK for now just knowing that's it's a template in which stuff in between <% ... %> will be replaced accordingly.

After creating the file, simply copy the following to it (replace the information inside the ModulePrefs accordingly!):

Now, we need to tell Sproutcore to use this file, this is easily done by adding a config[:layout] directive to the Buildfile:

config :all, :required => :sproutcore do |c|
  c[:resources_relative] = true
  c[:url_prefix] = 'http://groupdock.com:8090'
  c[:layout] = 'index.rhtml'  
end

Use absolute URLs for your HTTP resources

If your application was making calls to your backend using relative URLs such as /posts/1, you need to replace these by absolute URLs (e.g. http://yourhostname.com/posts/1).

Change AJAX calls to backend servers to makeRequest() calls

Our application currently does not make any AJAX calls to our backend server but your application most likely will. In order for these to work, you have to replace them with gadgets.io.makeRequest() calls. (See Documentation).

Testing the application on GroupDock and iGoogle

Once you've made the changes highlighted in the previous section, your application is now an OpenSocial application which can be deployed in OpenSocial containers such as GroupDock or iGoogle.

Adding to iGoogle

If you don't already have an iGoogle account, create one and log on to igoogle.com. After logging, add the My Gadgets gadget to your page. This gadget was build for developers to easily manage the gadgets they want to add to their page.

Once you have the My Gadgets gadget on your iGoogle page, simply add a new gadget by adding the url to yourhostname.com:8090/ as shown below:

After hitting the 'Add' button, your application should load in iGoogle as shown below.

Adding to GroupDock

In order to add your application to GroupDock, first you need to install this GroupDock application for developers. Once installed, launch it and click on the 'Create Application' link. From there, use the your application hostname URL (yourhostname.com:8090) to add the application.

Summary

In this tutorial, we started building a simple Hello World application from scratch in Sproutcore. We then converted this application to an OpenSocial application that we can deploy on GroupDock. Along the way, we learned how to deploy SproutCore applications to a web server.

We hope this tutorial was helpful. For more resources on building OpenSocial and Sproutcore applications for GroupDock, visit our Developer Site at dev.groupdock.com.

If you want to see the code for the completed application, you can find it on github at github.com/groupdock/HelloSprouts.

Extra: A rake task to deploy your sproutcore application in one step

We've shown you how to manually deploy a sproutcore application to your server. Obviously, you would want to automate that. Here is a Rakefile that you can add to your server that will let you deploy the application by just running rake deploy. The rake tasks does everything we've done earlier for you: builds the application, tar the files, moves them to the server, and create the symlink.

Make sure your replace the USER, HOSTNAME, APPLICATION, and PORT constants accordingly.

The End