eXo Platform 3.5

## Chapter 3. Applications Development

This chapter provides you with significant knowledge of 2 main applications in GateIn 3.2 that allows you to develop them efficiently:

- Portlet development

  Details of Portlet Primer and global `porlet.xml` file.

- Gadget development

  Information about a list of gadgets, and how to set up a Gadget Server.

## 3.1. Portlet development

- Portlet Primer

  Overall information about JSR-168 and JSR-286, and tutorials on deploying portlets and examples of JavaServer Pages Portlet.

- Global porlet.xml file

  Introduction to the global portlet purpose and knowledge of global metadata.

After reading this section, you will gain certain knowledge of portlets you need to know before developing a portlet in a portal.

`See also`

- Gadget development

### 3.1.1. Portlet Primer

JSR-168 and JSR-286 overview

The Java Community Process (JCP) uses Java Specification Requests (JSRs) to define proposed specifications and technologies designed for the Java platform.

The Portlet Specifications aim at defining portlets that can be used by any JSR-168 (Portlet 1.0) or JSR-286 (Portlet 2.0) portlet container.

Most Java EE (Enterprise Edition) portals include at least one compliant portlet container, and GateIn 3.2 is no exception. In fact, GateIn 3.2 includes a container that supports both versions.

This chapter gives a brief overview of the Portlet Specifications, but portlet developers are strongly encouraged to read the JSR-286 Portlet Specification .

GateIn 3.2 is fully JSR-286 compliant. Any JSR-168 or JSR-286 portlet operates as it is mandated by the respective specifications inside the portal.

- Portal Pages

  A portal can be considered as a series of web pages with different areas within them. Those areas contain different windows and each window contains portlet. The diagram below visually represents this nesting:

- Rendering Modes

  A portlet can have different view modes. Three modes are defined by the JSR-286 specification:

  View

    Generate the markup reflecting the current state of the portlet.

  Edit

    Allow you to customize the behavior of the portlet.

  Help

    Provide information to the user as to how to use the portlet.

- Window States

  Window states are an indicator of how much page space a portlet consumes on any given page. The three states defined by the JSR-168 specification are:

  Normal

    A portlet shares this page with other portlets.

  Minimized

    A portlet may show very little information, or none at all.

  Maximized

    A portlet may be the only portlet displayed on this page.

#### Deploying your first Portlet

### Note

- The tutorials contained in this chapter are targeted towards portlet developers. It is also recommended that developers read and understand the JSR-286 Portlet Specification .

- This example is using Maven to compile and build the web archive. Maven versions can be downloaded from maven.apache.org

This section describes how to deploy a portlet in GateIn 3.2. A sample portlet called SimplestHelloWorld is located in the examples directory at the root of your GateIn 3.2 binary package. This sample is used in the following examples.

##### Compiling

To compile and package the application:

1. Navigate to the SimplestHelloWorld directory and execute:

       mvn package

2. If the compile is successfully packaged, the result will be available in: SimplestHelloWorld/target/SimplestHelloWorld-0.0.1.war .

3. Copy the package file into $PLATFORM_JBOSS_HOME/server/default/deploy.

4. Start the JBoss Application Server (if it is not already running).

5. Create a new portal page and add the portlet to it.

##### Package Structure

Like other Java EE applications, GateIn 3.2 portlets are packaged in the .war files. A typical portlet .war file can include servlets, resource bundles, images, HTML, JavaServer Pages (JSP), and other static or dynamic files.

The following is an example of the directory structure of the SimplestHelloWorld portlet:

    |-- SimplestHelloWorld-0.0.1.war
    |   `-- WEB-INF
    |       |-- classes
    |       |   `-- org
    |       |       `-- gatein
    |       |           `-- portal
    |       |               `-- examples
    |       |                   `-- portlets
    |       |                       `-- SimplestHelloWorldPortlet.class
    |       |-- portlet.xml
    |       `-- web.xml

| The compiled Java class implementing javax.portlet.Portlet (through javax.portlet.GenericPortlet )
| This is the mandatory descriptor files for portlets. It is used during deployment.
| This is the mandatory descriptor for web applications.

##### Portlet Class

Below is the SimplestHelloWorldPortlet/src/main/java/org/gatein/portal/examples/portlets/SimplestHelloWorldPortlet.java Java source:

    package org.gatein.portal.examples.portlets;

    import java.io.IOException;

    import java.io.PrintWriter;

    import javax.portlet.GenericPortlet;

    import javax.portlet.RenderRequest;

    import javax.portlet.RenderResponse;

    public class SimplestHelloWorldPortlet extends GenericPortlet

    {

       public void doView(RenderRequest request,

                           RenderResponse response) throws IOException

       {

          PrintWriter writer = response.getWriter();

          writer.write("Hello World !");

          writer.close();

       }

    }

| All portlets must implement the javax.portlet.Portlet interface. The portlet API provides a convenient implementation of this interface. The javax.portlet.Portlet interface uses the javax.portlet.GenericPortlet class which implements the Portlet render method to dispatch to abstract mode-specific methods. This makes it easier to support the standard portlet modes. Portlet render also provides a default implementation for the processAction, init and destroy methods. It is recommended to extend GenericPortlet for most cases.
| If only the view mode is required, only the doView method needs to be implemented. The GenericPortlet render implementation calls our implementation when the view mode is requested.
| Use the RenderResponse to obtain a writer to be used to produce content.
| Write the markup to display.
| Close the writer.

### Markup Fragments

Portlets are responsible for generating markup fragments, as they are included on a page and are surrounded by other portlets. This means that a portlet outputing HTML must not output any markup that cannot be found in a <body> element.

##### Application Descriptors

GateIn 3.2 requires certain descriptors to be included in a portlet WAR file. These descriptors are defined by the Jave EE (web.xml) and Portlet Specification (portlet.xml).

Below is an example of the SimplestHelloWorldPortlet/WEB-INF/portlet.xml file. This file must adhere to its definition in the JSR-286 Portlet Specification. More than one portlet application may be defined in this file:

    <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"

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

       xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd

                                             http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"

       version="2.0">

       <portlet>

          <portlet-name>SimplestHelloWorldPortlet</portlet-name>

          <portlet-class>

             org.gatein.portal.examples.portlets.SimplestHelloWorldPortlet

          </portlet-class>

          <supports>

            <mime-type>text/html</mime-type>

          </supports>

          <portlet-info>

              <title>Simplest Hello World Portlet</title>

          </portlet-info>

       </portlet>

    </portlet-app>

| Define the portlet name. It does not have to be the class name.
| The Fully Qualified Name (FQN) of your portlet class must be declared here.
| The <supports> element declares all of the markup types that a portlet supports in the render method. This is accomplished via the <mime-type> element, which is required for every portlet. The declared MIME types must match the capability of the portlet. It allows administrators to pair which modes and window states are supported for each markup type. This does not have to be declared as all portlets must support the view portlet mode. Use the <mime-type> element to define which markup type the portlet supports. In the example above, this is text/html. This section tells the portal to only output HTML.
| When rendered, the portlet's title is displayed as the header in the portlet window, unless it is overridden programmatically. In the example above, the title would be Simplest Hello World Portlet .

#### JavaServer Pages Portlet Example

This section discusses:

1. Add more features to the previous example.

2. Use a JSP page to render the markup.

3. Use the portlet tag library to generate links to the portlet in different ways.

4. Use the other standard portlet modes.

### Note

The example used in this section can be found in the JSPHelloUser directory.

1. Execute mvn package in this directory.

2. Copy JSPHelloUser/target/JSPHelloUser-0.0.1.war to the deploy directory of JBoss Application Server.

3. Select the new JSPHelloUser tab in your portal.

### Note

The EDIT button only appears with logged-in users, which is not the case in the screenshot.

##### Package Structure

The package structure in this tutorial does not much differ from the previous example, with the exception of adding some JSP files detailed later.

The JSPHelloUser portlet contains the mandatory portlet application descriptors. The following is an example of the directory structure of the JSPHelloUser portlet:

    JSPHelloUser-0.0.1.war
        |-- META-INF
        |   |-- MANIFEST.MF
        |-- WEB-INF
        |   |-- classes
        |   |   `-- org
        |   |       `-- gatein
        |   |           `-- portal
        |   |               `-- examples
        |   |                   `-- portlets
        |   |                       `-- JSPHelloUserPortlet.class
        |   |-- portlet.xml
        |   `-- web.xml
        `-- jsp
            |-- edit.jsp
            |-- hello.jsp
            |-- help.jsp
            `-- welcome.jsp

##### Portlet Class

The code below is from the `JSPHelloUser/src/main/java/org/gatein/portal/examples/portlets/JSPHelloUserPortlet.java` Java source. It is split in different pieces.

    package org.gatein.portal.examples.portlets;

    import java.io.IOException;

    import javax.portlet.ActionRequest;

    import javax.portlet.ActionResponse;

    import javax.portlet.GenericPortlet;

    import javax.portlet.PortletException;

    import javax.portlet.PortletRequestDispatcher;

    import javax.portlet.RenderRequest;

    import javax.portlet.RenderResponse;

    import javax.portlet.UnavailableException;

    public class JSPHelloUserPortlet extends GenericPortlet

    {

       public void doView(RenderRequest request, RenderResponse response)

           throws PortletException, IOException

       {

          String sYourName = (String) request.getParameter("yourname");

          if (sYourName != null)

          {

             request.setAttribute("yourname", sYourName);

             PortletRequestDispatcher prd =

                getPortletContext().getRequestDispatcher("/jsp/hello.jsp");

             prd.include(request, response);

          }

          else

          {

             PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/welcome.jsp");

             prd.include(request, response);

          }

       }

    ...

| Override the doView method (as in the first tutorial).
| This entry attempts to obtain the value of the render parameter named yourname. If defined, it should redirect to the hello.jsp JSP page or to the welcome.jsp JSP page.
| Get a request dispatcher on a file located within the web archive.
| Perform the inclusion of the markup obtained from the JSP.

Like the VIEW portlet mode, the specification defines two other modes; EDIT and HELP.

These modes need to be defined in the portlet.xml descriptor. This enables the corresponding buttons on the portlet's window.

The generic portlet that is inherited dispatches different views to the methods: doView , doHelp and doEdit.

        ...

       protected void doHelp(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException,

             UnavailableException

       {

          rResponse.setContentType("text/html");

          PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/help.jsp");

          prd.include(rRequest, rResponse);

       }

       protected void doEdit(RenderRequest rRequest, RenderResponse rResponse) throws PortletException, IOException,

             UnavailableException

       {

          rResponse.setContentType("text/html");

          PortletRequestDispatcher prd = getPortletContext().getRequestDispatcher("/jsp/edit.jsp");

          prd.include(rRequest, rResponse);

       }

    ...

Portlet calls happen in one or two phases: when the portlet is rendered and when the portlet is actioned and then rendered.

An action phase is a phase where containing some state changes. The render phase will have access to render parameters that will be passed each time the portlet is refreshed (with the exception of caching capabilities).

The code to be executed during an action has to be implemented in the processAction method of the portlet.

        ...

             public void processAction(ActionRequest aRequest, ActionResponse aResponse) throws PortletException, IOException,

             UnavailableException

       {

          String sYourname = (String) aRequest.getParameter("yourname");

          aResponse.setRenderParameter("yourname", sYourname);

       }

    ...

| processAction is the method from GernericPorlet to override for the action phase.
| Here the parameter is retrieved through an action URL .
| The value of yourname is kept to make it available in the rendering phase. The previous line simply copies action parameters to a render parameter for this example.

##### JSP files and the Portlet Tag Library

The help.jsp and edit.jsp files are very simple. Note that CSS styles are used as defined in the portlet specification. This ensures that the portlet will render successfully within the theme and across portal vendors.

    <div class="portlet-section-header">Help mode</div>

    <div class="portlet-section-body">This is the help mode where you can find useful information.</div>

    <div class="portlet-section-header">Edit mode</div>

    <div class="portlet-section-body">This is the edit mode where you can change your portlet preferences.</div>

The landing page contains the links and form to call the portlet:

    <%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>

    <div class="portlet-section-header">Welcome !</div>

    <br/>

    <div class="portlet-font">Welcome on the JSP Hello User portlet,
    my name is GateIn Portal. What's yours ?</div>

    <br/>

    <div class="portlet-font">Method 1: We simply pass the parameter to the render phase:<br/>
    <a href="<portlet:renderURL><portlet:param name="yourname" value="John Doe"/>
                    </portlet:renderURL>">John Doe</a></div>

    <br/>

    <div class="portlet-font">Method 2: We pass the parameter to the render phase, using valid XML:
    Please check the source code to see the difference with Method 1.
    <portlet:renderURL var="myRenderURL">
        <portlet:param name="yourname" value='John Doe'/>
    </portlet:renderURL>
    <br/>
    <a href="<%= myRenderURL %>">John Doe</a></div>

    <br/>

    <div class="portlet-font">Method 3: We use a form:<br/>

    <portlet:actionURL var="myActionURL"/>
    <form action="<%= myActionURL %>" method="POST">
             <span class="portlet-form-field-label">Name:</span>
             <input class="portlet-form-input-field" type="text" name="yourname"/>
             <input class="portlet-form-button" type="Submit"/>
    </form>
    </div>

| The portlet taglib which needs to be declared.
| The first method shown here is the simplest one. portlet:renderURL will create a URL that calls the render phase of the current portlet and append the result at the place of the markup (within a tag). A parameter is also added directly to the URL.
| In this method, the var attribute is used. This avoids having one XML tag within another. Instead of printing the url, the portlet:renderURL tag will store the result in the referenced variable ( myRenderURL).
| The variable myRenderURL is used like any other JSP variable.
| The third method mixes the form submission and action request. Again, a temporary variable is used to put the created URL into.
| The action URL is used in the HTML form.

In the third method, the action phase is triggered first, then the render phase is triggered, which outputs some content back to the web browser based on the available render parameters.

##### JSF example using the JBoss Portlet Bridge

To write a portlet using JSF, it is required to have a 'bridge'. This software allows developers to write a portlet application as if it was a JSF application. The bridge then negotiates the interactions between the two layers.

An example of the JBoss Portlet Bridge is available in examples/JSFHelloUser. The configuration is slightly different from a JSP application. This example can be used as a base to configure instead of creating a new application.

As in any JSF application, the file faces-config.xml is required. It must contain the following information:

    <faces-config>

    ...

        <application>

          <view-handler>org.jboss.portletbridge.application.PortletViewHandler</view-handler>

          <state-manager>org.jboss.portletbridge.application.PortletStateManager</state-manager>

       </application>

    ...

    </faces-config>

The portlet bridge libraries must be available and are usually bundled with the WEB-INF/lib directory of the web archive.

The other differences as compared to a regular portlet application can be found in the portlet descriptor. All details about it can be found in the JSR-301 specification that the JBoss Portlet Bridge implements.

    <?xml version="1.0" encoding="UTF-8"?>

    <portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"

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

       xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd

                                             http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"

       version="2.0">

       <portlet>

          <portlet-name>JSFHelloUserPortlet</portlet-name>

          <portlet-class>javax.portlet.faces.GenericFacesPortlet</portlet-class>

          <supports>

             <mime-type>text/html</mime-type>

             <portlet-mode>view</portlet-mode>

             <portlet-mode>edit</portlet-mode>

             <portlet-mode>help</portlet-mode>

          </supports>

          <portlet-info>

             <title>JSF Hello User Portlet</title>

          </portlet-info>

          <init-param>

             <name>javax.portlet.faces.defaultViewId.view</name>

             <value>/jsf/welcome.jsp</value>

          </init-param>

          <init-param>

             <name>javax.portlet.faces.defaultViewId.edit</name>

             <value>/jsf/edit.jsp</value>

          </init-param>

          <init-param>

             <name>javax.portlet.faces.defaultViewId.help</name>

             <value>/jsf/help.jsp</value>

          </init-param>

       </portlet>

    </portlet-app>

| All JSF portlets define javax.portlet.faces.GenericFacesPortlet as the portlet class. This class is part of the JBoss Portlet Bridge.
| This is a mandatory parameter to define what's the default page to display.
| This parameter defines which page to display on the 'edit' mode.
| This parameter defines which page to display on the 'help' mode.

### 3.1.2. Global porlet.xml file

Global portlet.xml usecase

The Portlet Specification introduces PortletFilter as a standard approach to extend the behaviors of portlet objects. For example, a filter can transform the content of portlet requests and portlet responses. According to the Portlet Specification, normally there are 3 steps in setting up a portlet filter:

1. Implement a PortletFilter object

2. Define the filter in portlet application deployment descriptor

3. Define the filter mapping in portlet definitions

Two first steps are quite simple and easy to be done, however, at the step 3, developers/administrators need to replicate the filter mapping in many portlet definitions, that makes work error and tedious in several use cases. The global portlet feature is designed to compensate such limitation.

Global metadata

The Global metadata is declared in the `portlet.xml` file conforming with Portlet 2.0 's XSD.

    <portlet-app version="1.0" xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd"

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

                 xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd">

    </portlet-app>

- Location

  The path to the global `portlet.xml` is value of gatein.portlet.config in the `configuration.properties` file and varied by hosting application servers.

  - For Tomcat: `$PLATFORM_TOMCAT_HOME/gatein/conf/portlet.xml`

  - For JBoss: `$PLATFORM_JBOSS_HOME/server/default/conf/gatein/portlet.xml`

- Global metadata elements

  The global `portlet.xml` file conforms to the schema of the portlet deployment descriptor defined in the Portlet Specification with some restrictions. In this file, the following elements are supported:

  - Portlet filter: The Portlet filter mappings declared in the global`portlet.xml` file are applied across portlet applications. With the XML configuration below, the filter ApplicationMonitoringFilter involves in request handling on any deployed portlet.

        <filter>

             <filter-name>org.exoplatform.portal.application.ApplicationMonitoringFilter</filter-name>

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

            <lifecycle>ACTION_PHASE</lifecycle>

            <lifecycle>RENDER_PHASE</lifecycle>

            <lifecycle>EVENT_PHASE</lifecycle>

            <lifecycle>RESOURCE_PHASE</lifecycle>

        </filter>

  - Application Monitoring Filter: This filter supports 4 lifecycle phases as the order below: ACTION_PHASE/ EVENT_PHASE/ RENDER_PHASE/ RESOURCE_PHASE and records statistic information on deployed portlets. The filter alternates actual monitoring mechanism in WebUI Framework.

  - Portlet Mode and Window State: The global `portlet.xml` file is considered as an alternative place to declare custom Portlet Modes and Window States.

## 3.2. Gadget development

- Gadgets

  Knowledge of default gadgets on the system or remote ones and how to create new ones, edit/delete/import them or view them on the dashboard, and more.

- Standard WebApp for Gadget importer

  Instruction on how to create a WebApp which has a standard structure processed by the Gadget importer.

- Set up a Gadget Server

  Instructions on how to configure the gadget host and knowledge about security key for gadget container, gadget proxy and concat configuration.

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

`See also`

- Portlet development

### 3.2.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.

Existing Gadgets

Create a new Gadget

Remote Gadget

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

Gadget Importing

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

Gadget Web Editing

Modify it from the Web where the Gadget was imported:

Gadget IDE Editing

Edit it from your IDE thanks to the WebDAV protocol:

Dashboard Viewing

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

### 3.2.2. 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. It covers the following topics:

- Structure of WebApp

- Necessary files

- Local gadget resources

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.

### 3.2.3. Set up a Gadget Server

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`).

#### Configure 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.

#### Configure Gadget proxy and Concat

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?"
    },

Configure 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