Wednesday Oct 29, 2008

This Spec is My Spec, This Spec is Your Spec....

As OpenSocial is getting ready for version 0.9, a number of changes/clarifications/additions/etc are being proposed on the spec discussion page. I've submitted two of them based on things we're doing in Project SocialSite. Feedback is always welcome, and here's your chance to help shape OpenSocial (and, therefore, Project SocialSite).

The first is a proposal for messaging support. There was already a proposal for sending messages, but after working on the messaging implementation in SocialSite we had a (hopefully) good idea about what else would be useful. The current messaging proposal adds not just the ability to send messages, but also to retrieve, update, and delete them. It includes some changes to the message object to include sender information as well as a way for gadgets to send a payload in cases where this would be useful (e.g., group information in a group join request). Feel free to comment on the discussion thread or vote on the proposal.

The second proposal, discussed here on the spec group page, is about a change to the recipient format used in OpenSocial messages. We're trying to find the best (or at least most acceptable) way to specify not just the ID of the recipient, but whether or not it's a person, a group, or whatever else could be receiving messages in the future. Any input would be good here, or send us a note on the dev mailing list if you'd just like to know more about the implementation of our messaging support.

Thursday Oct 09, 2008

Screen Cast: Developing Project SocialSite

As more and more people are trying out Project SocialSite, we're finding out that some people want to be able to download and use the latest code without waiting for a promoted build. So this blog is for the code-happy developer types who want to build and try things out, and then rebuild and re-try if we (or they!) fix some particular issue. This isn't necessarily the best or only way to install SocialSite and then get into the twiddle/compile/test cycle (twiddle being the technical term), but it works for me.

As background, this blog assumes that you've downloaded the code, have an instance of GlassFish ready, already have ant, etc. There are a couple files that I have ready beforehand in the screen cast. Two are properties files that I edit ahead of time and copy somewhere else. You can do the same if you'd like:

  • socialsite/installer/sjsas.props
  • socialsite/installer/socialsite.props

The other step I mention in the screen cast is to change the property in socialsite/src/java/com/sun/socialsite/config/ After that, you're ready to follow along with the screencast.

I use FireFox as my browser, and there are a couple extensions that are very helpful when working on Project SocialSite or pretty much any other web application. You can find them both through FireFox's "Get Add-Ons" functionality, but here are some links as well:

  • Firebug. Can't live without this one. I use it for debugging JavaScript code and for checking the outgoing/incoming messages for requests made by gadgets. If you're working on gadget code and want to see what some generated html is really doing in a page, "Inspect Element" is a handy feature.
  • Web Developer. This extension does a lot more than I use it for, but it's essential for a couple things. The biggest for me is turning off my browser's cache so that it doesn't keep loading an old version of a gadget xml file long after I've made changes. Being able to clear your session data is nice as well when working on login/authentication. This extension does just about anything to a web page that you'd like.

Wednesday Oct 01, 2008

SocialSite, Gadgets, and You(r Web Site)

In a previous SocialSite blog, I had a short screen cast that described in brief what your web site needs to do to include SocialSite gadgets. To save you some clicking, here it is again. In this blog, I'll give some more information, and, if you follow along, a complete working example. A simple example, but a working example.

In a recent email thread on our users list, Dave broke the integration down into three necessary steps:

  1. Add an authentication delegator page to your web app
  2. Add the SocialSite context and Gadgets to pages in your app
  3. Add socialsite_context.xml to SocialSite to specify your app's delegator page
I'll cover the steps here, starting with some pre-work.

Step 0, part A

Have a web site. In this example, I've used NetBeans to create a simple web app. No frameworks, nothing fancy, just a simple web app called SimpleWebApp with the default index.jsp file that is created for you. For this web app, the index.jsp page could be reached at http://localhost:8080/SimpleWebApp/. Start NetBeans, choose New Project, then Java Web -> Web Application and follow the prompts.

Step 0, part B

Install SocialSite. If you haven't done that yet, you're in the wrong blog. However, here are some steps that are necessary for getting gadgets running. When you first install SocialSite and go to the web app in a browser, you'll see a login form in the middle like this:

Login Form

If you already have users in your web application, you can register them here. For this example, I've clicked Want to register? and entered this information (the password, not that it matters, was password):

New User Information

Note: In one email to our user's list, someone tried using the built-in "admin" user in a sample web app. By default, the "admin" user has no profile and so the gadgets won't work until you create a profile. For instance, if you log into SocialSite as the admin you'll see this on the main page:

Admin has no profile

Step 1

Add an authentication delegator page to your web app. In the screen cast, this is the socialsite_context.jsp or context.html.erb file. A request for this file is sent by the SocialSite server, sending the same cookies to your web app that the client would. It's how your site can assert the identity of the current user to SocialSite. A real-life example of this file is in the socialsite workspace. For my simple web app that has no user authentication, I've hard-coded the user for demonstration purposes. Just create a socialsite_context.jsp page in your simple app and add this:

<%@ page language="java" %>
<%@ page contentType="application/json" %>
  'attributes': {
    <%-- demonstration only! --%>
    'viewerId': 'newuser'

In a real web app, make sure you specify the user here the same way you would in your other web pages, either with request.getRemoteUser() for Java EE container authentication or however you're handling authentication.

Step 2

Add the SocialSite context and Gadgets to pages in your app. Now you can add gadgets to your pages, though first you need to add some context for SocialSite. In this example (save file and open in an editor), I've added two javascript elements at the top to load information from SocialSite and to tell SocialSite where I put the authentication delegator page. These calls need to be in all the pages that are going to include gadgets, so it's a good idea if you have a header jspf file or something similar to put them there. The calls look like this:

    <script type="text/javascript"
    <script type="text/javascript">
        'attributes': {
          'ownerId': 'newuser' <%-- hard coded for demo! --%>
        'delegate': {
          'method': 'GET',
          'url': 'http://localhost:8080/SimpleWebApp/socialsite_context.jsp',
          'headers': {
            'cookie': document.cookie

In the body of the page, now you can add the calls to load SocialSite gadgets. For example:

    <script type="text/javascript">
      socialsite.addGadget({'spec':'/local_gadgets/dashboard.xml', 'removable':false});

Step 3

Add socialsite_context.xml to SocialSite to specify your app's delegator page. You're almost there. Finally, you need to let SocialSite know that it's ok to communicate with an external app -- specifically, that it's ok to let another site assert the id of the user. To do this, add a socialsite_context.xml file to SocialSite's classpath. For my "SimpleWebApp" example, here is the file to use. Note that it contains the URL of the context delegator page that you added in step 1. One easy way to add this file to your classpath is to copy it to your glassfish/domains/domain1/lib/classes/ directory, which should already contain a file that was added during installation. Restart GlassFish to pick this up.

More official documentation is on the way, but I hope this helps you get started. Feel free to add comments, and follow along on the SocialSite blog for all the latest information.

Thursday Sep 04, 2008

It's the Little Things (That Keep Your Code From Working)

I was fiddling with a couple sample applications to use with Project SocialSite and found that none of the widgets I added to my pages were working. If you're unfamiliar with our widgets, they're little bits of JavaScript that you can add to your existing web pages in order to add social-networking functionality. Each one is written as a jMaki widget, and internally they each wrap a Google OpenSocial Gadget to provide the social networking UI.

So I had a couple new web apps that I created with NetBeans. With the jMaki plugin, I dragged some SocialSite widgets into the pages and ran the projects. "Unable to create an instance of Enable logging for more details.." Oops. Turning on debugging in jMaki's glue.js file at my web root, I see that the gadgetizer-core.js file on which the widgets rely was not found. In fact, it was missing from my project completely, when it should have been copied into /resources/socialsite/resources in my web root as described next.

All of the SocialSite widgets live in /resources/socialsite/widget-name-here, and each depends on a file, by convention, in /resources/socialsite/resources/. I can specify this file in a widget.json configuration file, and two things are supposed to happen. First, the jMaki plugin for my IDE copies this file into the web app when I add a widget. Second, the jMaki runtime loads this file before the widget so that it's available to the JavaScript engine when the page is viewed. In my case, I see that my resources aren't being added properly in my web apps. Even after I add them manually, I still see errors with the file not found in certain web frameworks.

The culprit? Well, I guess I am. I wrote the original widget.json files for our widgets, and somewhere along the way I messed up one tiny detail. Here is the widget.json file for our search widget. This version works:

    'name': 'Search Widget',
    'type': 'SocialSite',
    'jmakiVersion': '1.1',
    'version': '1.0',
    'description': 'Let\\'s a user search for people and/or groups .',
    'config': {
        'type': {
            'id': 'socialsite',
            'libs': [

What I had, however, was a URL in the config entry that was relative to the root of the web app:

    'libs': [

While this worked at runtime for some JSP apps, it failed in other cases where the routing to resource balked at the path I was using. Looking through some existing jMaki widgets (if using NetBeans, you can see all the code in $HOME/.netbeans/<version>/jmakicomplib), I found my mistake. I probably took some hasty notes early in our development, or somewhere along the way the files or jMaki changed.

We hope that Project SocialSite, besides being a useful addition to your own sites, also serves as a good example for writing your own Google Gadgets and/or jMaki widgets. If you're following along, though, make sure you pick up this change. Learning from your mistakes is good; learning from my mistakes saves you time.


Whatever part of GlassFish or the Java EE world that catches my attention. (Also, go Red Sox.)


« July 2016