Please pardon our appearance - we are upgrading the site. Thanks!

WebCenter Sites Gadget Development Concepts Quickstart

WebCenter Sites Gadget Development Concepts Quickstart
Tweet about this on TwitterShare on Google+Share on LinkedIn

What are Gadgets? At their most basic level they can be thought of as lightweight portlets that run largely on the client side of an architecture. Gadgets provide a cross-platform container to run reusable UI modules that generally expose dynamic information to an end user, allowing for some level of end user customization. Google’s Open Social Gadgets provide a series of standardized operations including, but not limited to authentication, personalization and inter-gadget communication.

At first, this new format may seem intimidating, but under a brief examination it becomes clear that development of gadgets can begin quickly with only a rudimentary understanding of the basics. In our code samples, we will just be scratching the surface and will provide links to detailed information to dive further into each topic. Our overview will cover the following

  1. Understanding Gadget Basics
  2. Gadget XML Structure and Most Basic Gadget
  3. Sample Intermediate Gadget
  4. Helpful Gadget Code Features
  5. Development Tools and Techniques
  6. Registering in WebCenter Sites
  7. Resources

Understanding Gadget Basics
Anyone familiar with Javascript / JQuery based client side development will be right at home when developing Gadgets. A Gadget uses client side code to generally interact with RESTful services that provide information to the Gadget in the form of JSON or XML.

The heart of Gadget functionality is outlined in the OpenSocial Core Gadget Specification as follows (adjusted for brevity)

A Gadget Container’s main function is to translate a Gadget XML file into content to deliver to the end user

Fetch the gadget XML using a Retrieve Content Request (Section 3.1).

1. Standard HTML header, opening tag and tag. information is optional. Gadgets run in browser quirks mode.
2. Core gadgets JavaScript libraries and any additional libraries specified in the gadget. The server SHOULD consolidate all librariess into a single request to minimize the number of HTTP requests made by the client browser. This MAY be followed by JavaScripte required to initialize the included libraries.
3. Results from parsing the Gadget XML file and processing the sections that match the specified View name.
4. A single call to gadgets.util.runOnLoadHandlers().
5. Standard HTML closing tags.
Containers must also be able to process Data Pipelining (Section 13) and Templating [OpenSocial­Templating] elements in the gadget XML spec.

Gadget XML Structure and Most Basic Gadget
Let’s take a pragmatic, pictorial look at the Gadget XML that you may want to create for your own Gadget. The following image represents an outline of the nodes within a Gadget XML file.

Let’s take a closer look at each of the segments above and get a sense for their specific function.

The first line of any Gadget must indicate what format the document is presented in – nothing fancy here. In this case we need to let the WebCenter Sites Gadget Server know that we are going to use an XML format with UTF-8 character encoding.

The Module node in our XML file will wrap the following 3 tags to contain all logic that is required for your Gadget.

In Module Prefs you can setup name value pairs to adjust the behavior of a gadget or system setting. This is not something for end users to work with, but for a developer setting up the Gadget for use by end users. Additionally, items like Title, Author and Gadget size can also be set within this area.

Within you will also set what libraries will be included for a particular Gadget. A common example would be <Require feature=”setprefs”/> that loads the JavaScript library for users to store preferences. Think of this as being similar to importing an library in Java.

The User Prefs section is optional, but will allow you to set options that a user can set to customize their experience. These options can be based on text fields, dropdowns and radio buttons – allowing for free form and controlled input from the end user. Please note that user preferences have a 2k size limit, due to being sent within a request header.

If you are familiar with HTML / JavaScript you will be right at home here. Within a gadget, the Content section will house the bulk of your code and beyond providing you will some additional JavaScript objects (like getting and setting user preferences), be no different from the coding that you do today with the exception that you must wrap your code in a CDATA block. This is what makes Gadget development so fast, once you get the hang of how the overall XML file is structured and why.

The following represents the most basic Gadget possible, notice that it even omits the UserPrefs section, as it leverages no user preferences.

Sample Intermediate Gadget
In the above gadget we were able to get a sense of the structure of a gadget and the minimum code that is required to

In the above example we incorporate some additional details in the ModulePref node to indicate the Author and the Title of the Gadget. More importantly for educational purposes, we also include a user preference. When the Gadget is used within WebCenter Sites, a Settings link will appear, allowing the user to set their name. The name is displayed in the body of the Gadget due to the __UP_username__ line. The following code is special, as it will replace a placeholder as follows

with the actual value of “prefname” or whatever preference you wish to use. __UP_ and the closing __ simply let the Gadget engine know that this area should be reserved for the value.

Helpful Gadget Code Features
The Gadget container provides some very helpful constructs to deliver the user experience and we have collected some of the top features below. As with the prior sections, this is by no means exhaustive, but represents some helpful code.

Example of Preference from Text Value

The following represents a simple example of a preference that can be stored for a user on the basis of a text value.

Example of Preference Options in List Format

To constrain user input within preferences, the following code can be used to present the user within a dropdown list of options. It is possible within lists to allow users to select one or more.

Getting Preferences

Once a user has set a preference, the following allow for the retrieval and storage into a variable for later use.

Gadget Views / Canvas and Navigation Between

It is possible to have a series of views that roughly equate to what may be Pages in traditional applications. For example, the following block of contains both a home and canvas view.

Within these pages it is possible to navigate between then, as well as pass data. In order to achieve this use a function similar to the one below to handle a link or button that may be clicked within the Gadget. When using this navigation note that you may need to include <Require feature=”views”> within your <ModulePrefs> section of XML.

This function would then be implemented using a link as follows

For more information about Views and Canvas check out Creating a User Interface – Gadgets API — Google Developers.

Passing Data Between Views

Extending the functions above, it is possible to pass some data along to a particular view, in the the following case we are going to pass some information along to the “canvas” view.

Tabs and MiniMessages

Tabs and MiniMessages are both nice interface helpers to expedite Gadget development. As you may expect the Tabs interface helper provides a series of visual tabs within your Gadget. The MiniMessages helper provides the ability for you to display a visual message within the Gadget for an end user that can be closed with a click.

By using <Requirefeature=”tabs”/> or <Requirefeature=”minimessage”/> within the <ModulePrefs> area of your Gadget, the system will load the corresponding JavaScript and CSS to support the usage of the Tab and MiniMessage constructs.

Due to the number of options and detail, head to for complete details of the Tab and MiniMessage use.

Dynamic Gadget Height

If you would like your Gadget to alter height when content is updated, the following will need to be included in your <ModulePrefs> section of your Gadget XML

Gadget to Gadget Communication

Similar to portlet development, you may want to have actions within one Gadget trigger events in other Gadgets. To enable this behavior, the concept of Publisher / Subscribed or pubsub is implemented. The following snippet highlights code that could be used within 2 different Gadgets to communicate with eachother. Please note that in order to leverage this, you must include <Require feature=”pubsub”/> in your <ModulePrefs>.

For some more full featured code samples that are platform independant, check out WSO2 Gadget Server – Inter Gadget Communication with Pub/Sub.

Development Tools and Techniques

Coding Prior to Inclusion in the Gadget XML

If you are creating a Gadget that will not rely on user preferences, or ones that can be hardcoded during testing, it is perfectly acceptable to run the Gadget only using the code that you will end up placing within the <Content> area of your XML markup.

External Content – JavaScript, Images and CSS

Single the Gadget ends up running in the browser like any general web markup, it is possible to include external files just as you would with normal development – nothing special is needed for the Gadget.

Eclipse Plugin

If you would like to develop your Gadgets within a self-contained environment there is a nice Eclipse plugin to assist development. A fair amount of functionality within the plugin is dedicated to Open Social data – which may not be a focus of enterprise Gadget development activities, but regardless it contains an embedded instance of Apache Shindig and will allow you to quickly run your Gadget for testing purposes.

You can download the plugin and view additional details at the address below

A tutorial for using the Open Social Development Environment is also available

Apache Shindig

Shindig is an open source implementation of the Open Social Gadget Container and will allow you to quickly test Gadgets without additional tools. If you are using a text editor to author your Gadgets, the following URL would allow Shindig to run your Gadget located at http://localhost/mygadget.xml.

Google Chrome and Cross Site Scripting

During development you may encounter JavaScript challenges due to your browser attempting to guard against cross site scripting (running JavaScript from another domain). In order to work around this for development some browsers allow you to turn this off, the following is an example of doing this with Chrome.

Registering in WebCenter Sites
Gadget registration in WebCenter Sites is a straightforward process – take a look at to see the registration in action.

Ready to become a Gadget development pro? Check out the following resources for more details around Gadget development.



  1. [...] in which WebCenter Sites supports this capability is in the form of Gadgets. In our previous post, WebCenter Sites Gadget Development Concepts Quickstart, we took at look at some of the fundamentals of Gadget [...]