Chapter 7. Work with Applications

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

This chapter will help you know how to integrate an application into your portal and how to develop your own 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 inside pages.xml:




<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 in HTML speaking.
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.

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.

For more information on how to develop gadgets and portlets, see in the GateIn Reference Guide:

Because a gadget is basically an independent HTML content, the gadget UI (layout, font, color, etc) may vary from gadgets to gadgets. Thus, getting all gadgets in eXo Platform to have the same look and feel is important. This mini-howto is intended for people who develop gadgets on eXo Platform to make sure their gadgets will have a consistent look and feel with eXo Platform skin, even when this skin may be changed in the future. It is assumed that you already knew how to write a gadget for using in eXo Platform.

To get more information about developing gadget, the following documents are useful:

  • Gadget development.

  • eXo Platform facilitates an easy gadget development via its powerful web-based IDE. You can refer to the IDE user guide here.

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 (style sheets, images, Javascript libraries, etc) 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 style sheets of the gadgets (exo-gadget/gadget-common.css) and other third-party components styles adapted to eXo Platform skin (jqPlot, Flexigrid,etc). 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 style sheets. When the eXo Platform skin is changed, updating style sheets in this file will affect all gadgets skins accordingly. In this file, you will define style sheets applied for all gadgets such as gadget title, gadget body, fonts, colors, tables, etc and some commonly used icons like drop down arrow, list bullet, setting button, etc.

  • 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.

  • etc.

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:

(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 in exo-gadget-resources is 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, etc) 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 choose an image of this size in PNG (preferred), JPG or GIF format for your gadget thumbnail.

  • The image can also be an image from a public web site (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-icon_80x80.png"/>

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.

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.

http://jboss.org/portletbridge/docs.html