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:
* [Application integration|#DEV.WorkWithApplications.ApplicationIntergration]
* [Develop your own applications|#DEV.WorkWithApplications.DevelopeYourOwnApplications]
** [Gadget vs Portlet|#DEV.WorkWithContent.GadgetvsPortlet]
** [Portlet Bridges|#DEV.WorkWithApplications.PortletBridges]
** [Portlet Bridges|#DEV.WorkWithApplications.PortletBridges]

h1. Application integration {anchor:id=DEV.WorkWithApplications.ApplicationIntergration}

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_:

{code: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>
{code}

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|http://platform.demo.exoplatform.org/docs/refguide/html/jcr/index.html]. |


h1. Develop your own applications {anchor:id=DEV.WorkWithApplications.DevelopeYourOwnApplications}

h2. Gadget vs Portlet {anchor:id=DEV.WorkWithContent.GadgetvsPortlet}

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:

* [Portlet development|http://docs.jboss.com/gatein/portal/3.1.0-FINAL/reference-guide/en-US/html_single/index.html#chap-Reference_Guide-Portlet_development]
* [Gadget development|http://docs.jboss.com/gatein/portal/3.1.0-FINAL/reference-guide/en-US/html_single/index.html#chap-Reference_Guide-Gadget_development]

h2. Gadget development in eXo Platform{anchor:id=DEV.WorkWithApplications}

h3. Preface
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|http://docs.jboss.com/gatein/portal/3.1.0-FINAL/reference-guide/en-US/html_single/index.html#chap-Reference_Guide-Gadget_development].
* eXo Platform facilitates an easy gadget development via its powerful web-based IDE. You can refer to the IDE user guide [here|http://community.exoplatform.org/rest/jcr/repository/knowledge/doc/PLF305/developer/html/ide-user-guide/index.html].

h3. Get the consistent look and feel

{docbook}
<citetitle>
<para>
<emphasis role="bold">Resources</emphasis>
</para>
</citetitle>
{docbook}

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: 

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

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:

* jquery/<version>:	jQuery Javascript library (http://jquery.com/).
* jquery/plugins/jqplot: Charts and Graphs for jQuery (http://www.jqplot.com/).
* jquery/plugins/flexigrid: Lightweight but rich data grid (http://flexigrid.info/).
* jquery/plugins/date.js: Javascript date library (http://www.datejs.com/).
* jquery/plugins/jquery.timers:	Javascript timer (http://plugins.jquery.com/project/timers).

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

{docbook}
<citetitle>
<para>
<emphasis role="bold">Apply for a gadget</emphasis>
</para>
</citetitle>
{docbook}

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: 

{code: language="xml"}
<?xml version="1.0" encoding="UTF-8" ?> 
<Module> 
<ModulePrefs title="Sample gadget" /> 
<Content type="html"> 
  <head> 
    <link rel="stylesheet" type="text/css" href="/exo-gadget-resources/skin/exo-gadget/gadget-common.css" /> 
    <script language="javascript" type="text/javascript" src="/exo-gadget-resources/script/jquery/1.6.2/jquery.min.js"></script> 
    <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>
{code}

The sample gadget:

!images/sample_gadget.png|align="center"!

{docbook}
<citetitle>
<para>
<emphasis role="bold">The sample user settings of a gadget</emphasis>
</para>
</citetitle>
{docbook}

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

{code: language="xml"}
<Module> 
<ModulePrefs title="Setting demo"> 
  <Require feature="dynamic-height"/> 
  <Require feature="setprefs"/> 
</ModulePrefs>  
<Content type="html"> 
  <head> 
    <link rel="stylesheet" type="text/css" href="/exo-gadget-resources/skin/exo-gadget/gadget-common.css"/> 
    <style type="text/css"> 
      .SettingButton:hover {cursor:pointer;} 
    </style>  
    <script language="javascript" type="text/javascript" src="/exo-gadget-resources/script/jquery/1.6.2/jquery.min.js"></script> 
    <script language="javascript" type="text/javascript"> 
<![CDATA[ 
      $(function(){ 
        var prefs = new gadgets.Prefs(); 
        var defaultNumItems = 3; 

        function displayItems(){ 
          var numItems = prefs.getInt("numItems") || defaultNumItems; 
          $("#content").html(""); 
          for(i=0; i<=numItems; i++) { 
            $("#content").append("<div class='IconLink'>Item " + (i+1) + "</div>");    (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"></div>   (1)
        </div> 
      </div> 
      <div class="GadCont"> 
        <div id="setting" style="display:none;">   (2)
          <label for="txtNumItems">Num of items</label> 
          <input type="text" id="txtNumItems"></input>                                       
          <input type="button" id="btnOk" value="OK"></input> 
          <input type="button" id="btnCancel" value="Cancel"></input> 
          <hr/> 
        </div> 
        <div id="content"></div> 
      </div> 
    </div> 
  </body> 
</Content> 
</Module> 
{code}

!images/setting_demo_form.png|align="center"!

{docbook}
<citetitle>
<para>
<emphasis role="bold">Customize the gadget thumbnail</emphasis>
</para>
</citetitle>
{docbook}

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. 

!images/gadget_thumbnail.png|align="center"!

* The image can also be an image from a public web site (absolute URL), for example: {noformat}<ModulePrefs title="Sample gadget" thumbnail="http://www.example.com/images/sample-icon.jpg"/>{noformat}

or from an internal image (relative URL): {noformat}<ModulePrefs title="Sample gadget" thumbnail="image/sample-icon_80x80.png"/>{noformat}




h2. Portlet Bridges {anchor:id=DEV.WorkWithApplications.PortletBridges}

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]
