eXo Platform 3.5

## Chapter 4. Gadget development

This chapter provides you all the basic knowledge about gadget developments through two following topics:

- Gadgets

- Set up a Gadget Server

With the knowledge you have gained, you will know how to deploy a gadget in GateIn 3.2.

## 4.1. Gadgets

A gadget is a mini web application, embedded in a web page and running on an application server platform. These small applications help users perform various tasks.

GateIn 3.2 supports gadgets, such as Todo, Calendar, Calculator, Weather Forecasts and RSS Reader.

Default Gadgets:

Calendar

  The calendar gadget allows you to switch easily between daily, monthly and yearly views. Also, this gadget is customizable to match your portal's theme.

ToDo

  This application helps you organize your day and work group. It is designed to keep track of your tasks in a convenient and transparent way. Tasks can be highlighted with different colors.

Calculator

  This mini-application lets you perform the most basic arithmetic operations and can be themed to match the rest of your portal.

RSS Reader

  An RSS reader, or aggregator collects content from various, user-specified feed sources and displays them in one location. This content can include, but is not limited to, news headlines, blog posts or email. The RSS Reader gadget displays this content in a single window on your Portal page.

More Gadgets

  Further gadgets can be obtained from the Google Gadget site. GateIn 3.2 is compatible with most of the gadgets available here.

### Important

The following sections require more textual information.

### 4.1.1. Existing Gadgets

### 4.1.2. Create a new Gadget

### 4.1.3. Remote Gadget

This is the reference to a remote gadget (stock one).

### 4.1.4. Gadget Importing

After referencing the gadget successfully, import it into the local repository.

### 4.1.5. Gadget Web Editing

Modify it from the Web where the Gadget was imported:

### 4.1.6. Gadget IDE Editing

Edit it from your IDE thanks to the WebDAV protocol:

### 4.1.7. Dashboard Viewing

View it from the Dashboard when you drag and drop the Gadget from listing to the dashboard.

### 4.1.8. Standard WebApp for Gadget importer

In GateIn 3.2, you can create a WebApp folder to contain the configuration of the list of gadgets which are automatically added to the Application Registry.

This section shows you how to create a WebApp which has a standard structure processed by the Gadget importer.

#### Structure of WebApp

A WebApp should be organized as the following structure:

#### Necessary files

The WebApp structure consists of two necessary files, including web.xml, and gadget.xml.

In the web.xml file, there are 2 requirements:

- The org.exoplatform.portal.application.ResourceRequestFilter filter: handle requests to map into GateIn.

- The org.gatein.wci.api.GateInServlet servlet: help to register this WebApp to GateIn.

    <web-app>

      <display-name>eXoGadgets</display-name>

      <filter>

        <filter-name>ResourceRequestFilter</filter-name>

        <filter-class>org.exoplatform.portal.application.ResourceRequestFilter</filter-class>

      </filter>

      <filter-mapping>

        <filter-name>ResourceRequestFilter</filter-name>

        <url-pattern>/*</url-pattern>

      </filter-mapping>

      <servlet>

        <servlet-name>GateInServlet</servlet-name>

        <servlet-class>org.gatein.wci.api.GateInServlet</servlet-class>

        <load-on-startup>0</load-on-startup>

      </servlet>

      <servlet-mapping>

        <servlet-name>GateInServlet</servlet-name>

        <url-pattern>/gateinservlet</url-pattern>

      </servlet-mapping>

    </web-app>

The gadget.xml file is used to locate the configuration of gadgets that you want to add to the Application Registry.

     <gadgets

        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

        xsi:schemaLocation="http://www.gatein.org/xml/ns/gatein_objects_1_0 http://www.gatein.org/xml/ns/gadgets_1_0"

        xmlns="http://www.gatein.org/xml/ns/gadgets_1_0">

        <gadget name="To-do">

            <path>/gadgets/Todo/Todo.xml</path>

        </gadget>

        <gadget name="Calendar">

            <path>/gadgets/Calendar/Calendar.xml</path>

        </gadget>

        <gadget name="Calculator">

            <path>/gadgets/Calculator/Calculator.xml</path>

        </gadget>

        <gadget name="rssAggregator">

            <path>/gadgets/rssAggregator/rssAggregator.xml</path>

        </gadget>

      <gadget name="Currency">

        <url>http://www.donalobrien.net/apps/google/currency.xml</url>

      </gadget>

      <gadget name="ServicesManagement">

        <path>/gadgets/ServicesManagement/ServicesManagement.xml</path>

      </gadget>

    </gadgets>

This file has 3 important tags:

- <gadget>: every gadget will be configured in the <gadget> tag which has a "name" attribute to indicate the gadget name that Application Registry manages. The <gadget> tag can contain a child tag, either <path>, or <url>.

- <path>: this tag is the child of the <gadget> tag. It indicates the path to the gadget and helps the Gadget service find exactly where the gadget source and resources are located. It is known as the local path of the server.

- <url>: if the gadget source is located from the external server, the <url> tag should be configured to indicate the URL of the gadget.

#### Local gadget resources

For local gadgets, their source and resources should be located in the same folder.

See the example about the To-do gadget:

### Note

The Gadget importer service will find a folder that contains the gadget source, then find all resources in the folder and store them into JCR as the resources of the gadget. Therefore, putting the gadget resources in the folder different from the gadget source can cause many unnecessary files to be stored as the resource files of the gadget.

## 4.2. Set up a Gadget Server

### 4.2.1. Virtual servers for gadget rendering

GateIn 3.2 recommends using two virtual hosts for security. If the gadget is running on a different domain other than the container (the website that 'contains' the app), it is unable to interfere with the portal by modifying the code or cookies.

An example would hosting the portal from http://www.sample.com and the gadgets from http://www.samplemodules.com.

To do this, configure a parameter called gadgets.hostName. The value is the path/to/gadgetServer in `GadgetRegisteryService`:

    <component>

      <key>org.exoplatform.application.gadget.GadgetRegistryService</key>

      <type>org.exoplatform.application.gadget.jcr.GadgetRegistryServiceImpl</type>

      <init-params>

        <value-param>

          <name>gadgets.hostName</name>

          <description>Gadget server url</description>

          <value>http://localhost:8080/GateInGadgetServer/gadgets/</value>

        </value-param>

      </init-params>

    </component>

It is also possible to have multiple rendering servers. This helps to balance the rendering load across multiple servers.

When deploying on the same server, ensure the gadget initiates before anything that calls it (for example; the webapp `GateInGadgets` which uses `org.exoplatform.application.gadget.GadgetRegister`).

### 4.2.2. Configuration

#### Security key

In GateIn, the gadget container is using three security files for authentication and authorization gadgets:

- key.txt

- oauthkey.pem

- oauthkey_pub.pem

By default, they are located in the tomcat/gatein/conf/gadgets folder and are configured by system variables in the tomcat/gatein/conf/configuration.properties file:

            gatein.gadgets.securitytokenkeyfile=${gatein.conf.dir}/gadgets/key.txt
            gatein.gadgets.signingkeyfile=${gatein.conf.dir}/gadgets/oauthkey.pem

In case you have other files, you can change these variables to point to them.

The key.txt file contains a secret key used to encrypt the security token used for the user authentication. When starting GateIn, this file is read via the gatein.gadgets.securitytokenkeyfile path. In case the key.txt file is not found, GateIn automatically generates a new key.txt one and save it to the gatein.gadgets.securitytokenkeyfile path.

oauthkey.pem and oauthkey_pub.pem are a key pair of RSA cryptography standard. oauthkey.pem is known as a private key and oauthkey_pub.pem is a public key. They are the default keys of the gadget container which OAuth gadgets will use to authorize with external service providers.

#### Gadget proxy and concat configuration

These servers have to be on the same domain as the gadget server. You can configure the container in eXoGadgetServer:/WEB-INF/classes/containers/default/container.js.

    "gadgets.content-rewrite" : {
      "include-urls": ".*",
      "exclude-urls": "",
      "include-tags": ["link", "script", "embed", "img", "style"],
      "expires": "86400",
      "proxy-url": "http://localhost:8080/eXoGadgetServer/gadgets/proxy?url=",
      "concat-url": "http://localhost:8080/eXoGadgetServer/gadgets/concat?"
    },

#### Proxy

To allow external gadgets when the server is behind a proxy, add the following code to the beginning of the JVM:

    -Dhttp.proxyHost=proxyhostURL -Dhttp.proxyPort=proxyPortNumber -Dhttp.proxyUser=someUserName -Dhttp.proxyPassword=somePassword

Copyright © 2009-2012. All rights reserved. eXo Platform SAS