eXo Platform 3.5

## Chapter 5. Work With Applications

Applications play an important role in each eXo service, so it is necessary for you to further understand about them.

In this chapter, you will know how to integrate an application into your portal, and how to develop your own application:

- Integrate an application

- Develop your own application

  - Gadget vs Portlet

  - Develop a gadget for eXo Platform

  - Portlet Bridges

## Integrate an application

To add a portlet to one of your portal's pages, you should configure the pages.xml file located at /war/src/main/webapp/WEB-INF/conf/sample-ext/portal/portal/classic/.

Here is an example of the portlet configuration in the pages.xml file:

    <portlet-application>

      <portlet>

        <application-ref>presentation</application-ref>

        <portlet-ref>SingleContentViewer</portlet-ref>

        <preferences>

          <preference>

            <name>repository</name>

            <value>repository</value>

            <read-only>false</read-only>

          </preference>

          <preference>

            <name>workspace</name>

            <value>collaboration</value>

            <read-only>false</read-only>

          </preference>

          <preference>

            <name>nodeIdentifier</name>

            <value>/sites content/live/acme/web contents/site artifacts/Introduce</value>

            <read-only>false</read-only>

          </preference>

          <!-- ... -->

        </preferences>

      </portlet>

      <title>Homepage</title>

      <access-permissions>Everyone</access-permissions>

      <show-info-bar>false</show-info-bar>

      <show-application-state>false</show-application-state>

      <show-application-mode>false</show-application-mode>

    </portlet-application>

Details:

XML tag name | Description
--- | ---
`application-ref` | The name of the webapp that contains the portlet.
`portlet-ref` | The name of the portlet.
`title` | The title of the page.
`access-permission` | Define who can access the portlet.
`show-info-bar` | Show the top bar with the portlet title.
`show-application-state` | Show the collapse/expand icons.
`show-application-mode` | Show the change portlet mode icon.
`preferences` | Contain a list of preferences specific to each portlet. Each preference has a name and a value. You can also lock it by setting the read-only element to "true". To learn more, refer to eXo JCR and Extension Services Reference.

## Develop your own application

### Gadget vs Portlet

It is important to understand distinctions between gadgets and portlets. Portlets are user interface components that provide fragments of markup code from the server side, while gadgets generate dynamic web content on the client side. With Gadgets, small applications can be built quickly, and mashed up on the client side using the lightweight Web-Oriented Architecture (WOA) technologies, like REST or RSS.

### Note

For more information on how to develop gadgets and portlets, see the Portlet development and Gadget development sections.

### Develop a gadget for eXo Platform

Because a gadget is basically an independent HTML content, the gadget UI such as layout, font, color may be different. Thus, making consistent in the look and feel of all eXo Platform gadgets is very important. In this part, it is assumed that developers have already known how to write a gadget in eXo Platform. The information here helps developers make a consistent look and feel with eXo Platform skin, even when this skin may be changed in the future.

### Note

To get more information on how to develop gadgets, see the Gadget development and Develop gadgets via a powerful web-based IDE of eXo Platform sections.

#### Get the consistent look and feel

Resources

To achieve the consistent look and feel, you have to collect the common features of all gadgets as much as possible and put in a place where it can be shared for all gadgets. You will use exo-gadget-resources for this purpose. It is a .war file that contains commonly used static resources (stylesheets, images, JavaScript libraries, and more) available for all gadgets in eXo Platform at runtime:

    /exo-gadget-resources
     |__skin
     |   |__exo-gadget
     |   |   |__images
     |   |   |__gadget-common.css
     |   |__...(3rd-party components' CSS)
     |__script
        |__jquery
        |  |__1.6.2
        |  |__...(other jQuery versions)
        |  |__plugins
        |__utils

The resources are divided into 2 categories: skin and script.

Skin: is the place for the shared stylesheets of the gadgets (exo-gadget/gadget-common.css) and other third-party components styles adapted to the eXo Platform skin (jqPlot, Flexigrid, and more). This is a copy of the component's original CSS with some modifications to match the eXo Platform's skin. You can find this original file at the component's folder under exo-gadget-resources/script , then link to it or make your own copy (put it in your gadget's folder and refer to it in gadget's .xml file) to suit your need.

The gadget-common.css file is the main place for the global stylesheets. When the eXo Platform skin is changed, updating stylesheets in this file will affect all gadgets skins accordingly. In this file, you will define stylesheets applied for all gadgets, such as gadget title, gadget body, fonts, colors, tables, and some commonly used icons, such as drop-down arrow, list bullet, setting button, and more.

For example:

- UIGadgetThemes: the gadget container.

- TitGad: the gadget title.

- ContTit: the gadget title content.

- GadCont: the gadget content.

- SettingButton: the setting button for gadget's User Preferences.

Script: is the place for commonly used third-party JavaScript libraries (e.g: jQuery and its plugins) and a library of useful utility scripts (the utils folder).

jQuery and plugins:

- jquery/<version>: jQuery JavaScript library.

- jquery/plugins/jqplot: Charts and Graphs for jQuery.

- jquery/plugins/flexigrid: Lightweight but rich data grid.

- jquery/plugins/date.js: JavaScript date library.

- jquery/plugins/jquery.timers: JavaScript timer.

(Here you should keep the latest and several versions of jQuery because some plugins may not work with the latest version. Several versions of a plugin are also kept).

The utilities scripts:

- utils/pretty.date.js: Calculate the difference from a point of time in the past to the present and display "4 months 3 weeks ago", for example.

Apply for a gadget

A gadget should use static resources available in exo-gadget-resources instead of including them in their own package. This helps reduce packaging size, avoid duplication (considering that every gadget includes a version of jQuery is in its own package) and take advantages of automatic skin changing/updating when the resources of exo-gadget-resources are updated to the new eXo Platform skin. To make it work, the applied gadget must use the CSS classes defined in gadget-common.css (at least for the gadget title) like the sample gadget below:

    <Module>

    <ModulePrefs title="Sample gadget"/>

    <Content type="html">

      <head>

        <link href="/exo-gadget-resources/skin/exo-gadget/gadget-common.css" rel="stylesheet" type="text/css"/>

        <script language="javascript" src="/exo-gadget-resources/script/jquery/1.6.2/jquery.min.js" type="text/javascript"/>

        <script language="javascript" type="text/javascript">

          $(function(){

            alert("Hello from jQuery");  (3)

          });

        </script>

      </head>

      <body>

        <div class="UIGadgetThemes">

          <div class="TitGad ClearFix">

            <div class="ContTit">Gadget title</div>  (1)

          </div>

          <div class="GadCont">  (2)

            Gadget content

          </div>

        </div>

      </body>

    </Content>

    </Module>

The sample gadget:

The sample user settings of a gadget

The following gadget gives the demo of a user settings screen which uses eXo Platform standard icons (setting button, list item bullet, and more) that are defined in the gadget-common.css.

    <Module>

    <ModulePrefs title="Setting demo">

      <Require feature="dynamic-height"/>

      <Require feature="setprefs"/>

    </ModulePrefs>

    <Content type="html">

      <head>

        <link href="/exo-gadget-resources/skin/exo-gadget/gadget-common.css" rel="stylesheet" type="text/css"/>

        <style type="text/css">

          .SettingButton:hover {cursor:pointer;}

        </style>

        <script language="javascript" src="/exo-gadget-resources/script/jquery/1.6.2/jquery.min.js" type="text/javascript"/>

        <script language="javascript" type="text/javascript">

          $(function(){

            var prefs = new gadgets.Prefs();

            var defaultNumItems = 3;

            function displayItems(){

              var numItems = prefs.getInt("numItems") || defaultNumItems;

              $("#content").html("");

              for(i=0; i&lt;=numItems; i++) {

                $("#content").append("&lt;div class='IconLink'&gt;Item " + (i+1) + "&lt;/div&gt;");    (3)

              }

              gadgets.window.adjustHeight($(".GadCont").get(0).offsetHeight);

            }

            $(".SettingButton").live("click", function(){

              $("#txtNumItems").val(prefs.getInt("numItems") || defaultNumItems);

              $("#setting").toggle();

              gadgets.window.adjustHeight($(".GadCont").get(0).offsetHeight);

            });

            $("#btnOk").live("click", function(){

              var sNumItems = $("#txtNumItems").val();

              prefs.set("numItems", parseInt(sNumItems) || defaultNumItems);

              $("#setting").hide();

              displayItems();

            });

            $("#btnCancel").live("click", function(){

              $("#setting").hide();

              gadgets.window.adjustHeight($(".GadCont").get(0).offsetHeight);

            });

            displayItems();

          });

        </script>

      </head>

      <body>

        <div class="UIGadgetThemes">

          <div class="TitGad ClearFix">

            <div class="ContTit">

              Setting demo

              <div class="SettingButton" style="display:block; width:20px; height:20px"/>   (1)

            </div>

          </div>

          <div class="GadCont">

            <div id="setting" style="display:none;">   (2)

              <label for="txtNumItems">Num of items</label>

              <input id="txtNumItems" type="text"/>

              <input id="btnOk" type="button" value="OK"/>

              <input id="btnCancel" type="button" value="Cancel"/>

              <hr/>

            </div>

            <div id="content"/>

          </div>

        </div>

      </body>

    </Content>

    </Module>

Customize the gadget thumbnail

The gadget thumbnails are displayed in the Page Editor window when you edit a page. The thumbnail image size needs to be consistent for all gadgets in the list. The current size (in eXo Platform 3.5) is 80 x 80px, so you should select an image of this size in PNG (preferred), JPG or GIF format for your gadget thumbnail.

- The image can also be one from a public website (absolute URL), for example: <ModulePrefs title="Sample gadget" thumbnail="http://www.example.com/images/sample-icon.jpg"/>; or from an internal image (relative URL): <ModulePrefs title="Sample gadget" thumbnail="image/sample-icon80x80.png"/>.

### Portlet Bridges

The Portlet Bridge is an adapter for a web framework to the portlet container runtime. It works ideally with framework that does not expose the servlet container with the limited support for the full portlet API.

The JavaTM Specification Request 168 Portlet Specification (JSR 168) standardizes how components for portal servers are developed. This standard has industry backing from major portal server vendors. A Portlet Bridge allows you to create a JSR-168 compliant portlet with very little change on your existing web application.

For example, the JSF Bridge allows you to transparently deploy your existing JSF Applications as a Portlet Application or Web Application. For more details, see http://wiki.apache.org/myfaces/PortletBridge.

The JBoss implementation of the Portlet Bridge has enhancements to support other web frameworks, such as RichFaces and Seam. For more details, see http://jboss.org/portletbridge/docs.html.