OpenSocial Plugin

  • Tags : /
  • Latest : 0.1
  • Last Updated: 31 January 2010
  • Grails version : 1.1.2 > *
  • Authors : PatrickHennig
1 vote
Dependency :
compile ":open-social:0.1"

Documentation

Summary

Installation

grails install-plugin open-social

Description

A plugin for creating OpenSocial gadgets

With this plugin, you can create OpenSocial gadgets right from your Grails app. You will be using <opensocial:...> tags declared in a tag library to define several aspects of your gadget. For example, one of these custom tags allow you to specify in your view that it will be a gadget view. You will be also refer to Grails controllers to specify which controller will handle actions originating from your gadget. After using view and controller with opensocial custom tags you'll be able to view your Grails App as a OpenSocial Gadget.

OpenSocial uses a XML document called a gaadget specification file to specify the gadget - it's presentation (using HTML and CSS for different gadget views) and behavior (using JavaScript and OpenSocial API).

Have in mind that this plugin as at a very early stage and that it does not offer flexibility to access all OpenSocial API calls. For example, activities, messaging and invitations are currently not supported at all, while support for people calls is basic.

With that in mind, we will now explain which custom tags you could use and what do they do.

Features

The current version of the openSocial plugin supports not the whole functionality of openSocial. But with this plugin it is possible to build basic openSocial Gadgets very easily. The version 0.1 supports the following features:

  • generating the xml structure
  • include external JavaScript and Stylesheets
  • generating xml content for multiple views (default, canvas, profile)
  • getting owner's user name
  • anchor other controllers and request it with AJAX
  • execute JavaScript in loaded AJAX request

Using the tag library

The plugin consists of a tag library, which automatically generates the XML document and its content.

Gadget XML

At the beginning you have to specify the XML structure for the gadget. This is very easy by writing the following line of code. You can specify the title of your Gadget in this line of code as well.

<opensocial:gadget title="my first Gadget">

...

</opensocial:gadget>

openSocial views

openSocial supports multiple views. If you want just one single view, you have to specify the following default view in the content of your gadget tag. With the attributes controller and action you specify what the gadget should load at startup.
…
<opensocial:view controller="startPage" action="index">
</opensocial:view>
...

Waiting body
To show something during the time the gadget loads the specified controller at startup, you can set the body of the view. But be aware that it will be replaced with the controllers content after loading.
…
<opensocial:view controller="startPage" action="index" viewName=”canvas”>
  You have to wait, until the gadget is loaded…
</opensocial:view>
...

Different gadget views
Because openSocial gadgets usually are used in social networks, you may want that the gadget looks different in different environments. Therefore, you can specify a viewName attribute with the name of the view. Valid values are for example "canvas" or "profile".
…
<opensocial:view controller="startPage" action="index" viewName=”canvas”>
</opensocial:view>
...

Send the user to the controller
If you want to get the owner's user name of the gadget you have to set the attribute sendUser to "true". Then the current user name of the owner will be send to the specified controller at startup.
…
<opensocial:view controller="startPage" action="index" sendUser=”true”>
</opensocial:view>
...

Use external JavaScript and Stylesheet files
The plugin also supports the option to load external JavaScript and Cascading Stylesheets. You just have to specify a JSON Object with two keys 'js' and 'css'. The values of both keys have to be an array of URLs.
…
<opensocial:view controller="startPage" action="index" 
               externalLinks="{js:['http://localhost/myJS.js',
                                   ‘http://locahost/another.js',],
                              css:['http:/localhost/mystyle.css']}'”>
</opensocial:view>
...

Execute JavaScript at startup
To execute JavaScript at startup you can set the attribute 'js' to execute JavaScript code.
…
<opensocial:view controller="startPage" action="index" js="window.alert(‘hallo’)”>
</opensocial:view>
...

openSocial links

Because gadgets run in a container you have to load new content with AJAX. You can use the link tag of the plugin to do this. So the specified action of the controller will be requested via AJAX and will replace the current content. Because the gadget runs in an external Container, you have to specify the ServerURL in the Config.groovy of your project. And be sure that ${app.name} is also set.

…
<opensocial:link controller="startPage" action="doSomething">
Go There
</opensocial:link>
...

Send GET attributes to the controller
To send additional attributes to a controller you just have to specify the parameters in an attribute. Set your paramters as a JSON string. The link will send these parameters as GET attributes to the controller where you can easily use them.
…
<opensocial:link controller="startPage" action="doSomething" attributes="{mykey:'myvalue'}">
Go There
</opensocial:link>
...

Execute JavaScript on clicked anchor
Maybe it is necassary to execute JavaScript immediately after someone clicks on a link. For example if you want to show a spinner or something like this.
…
<opensocial:link controller="startPage" action="doSomething" js="window.alert(‘you clicked’)">   
Go There
</opensocial:link>
...

Send a user name to the controller
A link tag also supports sending a username to the controller. Just set the attribute "user" for this purpose. In the controller, you can access the username via params"user" (+).
…
<opensocial:link controller="startPage" action="doSomething" user="myname">
Go There
</opensocial:link>
...

openSocial submit

Submitting a form can also be handled by the plugins tag library. The tag library serializes the form with prototype and sends the data to a controller as GET parameters. Serializing the form can only be done if the prototype library is included. You can load the prototpye library at the beginning with an external link as show above.

…
<opensocial:submit controller="startPage" action="doSomething" value="add it"/>
...

Send a user name to the controller
Just like the link tag, a submit button can also send a user name to the controller by setting the user attribute.
…
<opensocial:submit controller="startPage" action="doSomething" value="add it" user=”myname”/>
...

Execute JavaScript on clicked Anchor
For executing JavaScript on the click event, you can specify JavaScript code with the "js" attribute.
…
<opensocial:submit controller="startPage" action="doSomething" value="add it" js=”window.alert(‘button was clicked’)”/>
...

Testing the Gadget

It is very difficult to test Gadgets, because your development environment is usually not accesible from the world wide web. So you cannot test the gadget's functionality with iGoogle or other platforms that use openSocial.

One method is to paste the generated XML Code in a separated XML File, upload this on a server and try this out on iGoogle or something different.

Another method is to install the openSocial container implementation Shindig and the open source social network Partuza on the local system. This is the most comfortable method to test gadgets. But it is not very easy to install.

So we have prepared a VMWare image with running Shindig und Partuza to test your gadgets. You can download it from: http://www.hpi-web.de/.....zip

Additional Information

Because the gadgets will be executed in a container, the URLs have to be absolute. So you have to set your serverURL in your Config.groovy file like this:
grails.serverURL = "http://myip:8080/myappname";

If you want to create a Link, you can use the createLinkTo function from groovy. Becuase the gadget runs in a external container you have to set the attribute absolute to true like this:

${createLinkTo(dir:'js',file:'my.js',absolute:'true')}

The submit tag uses the prototype library. So you have to load this library at external links. You can do this like this:

<opensocial:view … externalLinks="{js:['${createLinkTo(dir:'js/prototype',file:'prototype.js',absolute:'true')}']}" >