Last updated by PatrickHennig 3 years ago

openSocial Plugin

Author: Patrick Hennig | Thomas Zimmermann

A plugin for easily creating openSocial Gadgets.

For installation type: 

grails install-plugin openSocial

It works very easy, you just have to specify in your view, that this view will be a gadget. Then you have to specify which controller you want to load in your view at startup. After this you are able to view your usual Grails App as a openSocial Gadget. openSocial uses a XML document to specify the gadget. The Plugin consists of a tag library, which automatically generates the XML document and its content.

Features

The current version of the openSocial Plugin supports not the whole functionality of openSocial. But with this Plugin it is posible to build very easily basic openSocial Gadgets. 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 owners´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="OPEN CANTEEN">
...
</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 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, so if you want that the gadget looks different in the profile, you can specify a viewname Attribute with the name of the view. Values are for example "canvas" or "profile" 
…
<opensocial:view controller="startPage" action="index"
viewName=”canvas”>
</opensocial:view>
...

enable to send the user to the controller
If you want, to get the owners 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 spedified controller at startup. 
…
<opensocial:view controller="startPage" action="index"
sendUser=”true”>
</opensocial:view>
...

use external JavaScript and Stylesheet files
The plugin also supports the possibility to load external JavaScript and Cascading Stylesheets. You just have to specify a JSON Object with two key 'js' and 'css'. The value of both keys have to be a 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 the Gadget runs in a Container you have to load new content with ajax. So 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 replaced 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 the ${app.name} is also set. 

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

send GET attributes to the controller
To send additional attributes to a controller you just have to specify the attributes paramter. Set your paramters as a JSON Object. The link will send theses Parameters as Get attributes to the controller. So you can easily use them in your controller. 
…
<opensocial:link controller="startPage" action="eatOffer"
attributes="{mykey:'myvalue'}">
Go There
</opensocial:link>
...

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

send a user name to the controller
At a link tag it is also supported to send a username to the controller. Just with the attribute "user" 
…
<opensocial:link controller="startPage" action="eatOffer"
user="myname">
Go There
</opensocial:link>
...
The feedType parameter is required. The feedVersion is optional and will default to 2.0 for RSS and 1.0 for Atom

openSocial submit

To submit a form you can also do this, by using the plugins tag library. The tag library serialize the form with prototype and send the data to a controller as attributes. To do this, the prototype library is needed. You can load the prototpye library at the beginning with external links 

…
<opensocial:submit controller="startPage" action="addCanteen" value="Hinzufügen"/>
...

send a user name to the controller
At a submit button you also can send a user name to the controller 
…
<opensocial:submit controller="startPage" action="addCanteen" value="Hinzufügen" user=”myname”/>
...

execute JavaScript on clicked Anchor
To execute JavaScript on the Click event, you can specify JavaScript code with the "js" attribute. 
…
<opensocial:submit controller="startPage" action="addCanteen" value="Hinzufügen" 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 this with iGoogle or other platforms using openSocial.

One method is to paste the generated XML Code in a seperated XML File, upload this on a server and try this in iGoole or somethin different.

Another method is to install the openSocial Container Implementation Shindig and the openSource Social Network Partuza on the local system. This is the most comfortable method to test gadgets. But it is not easy to install.

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

Additional Information

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

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

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