{docbook}
<abstract>
<para>Applications play an important role in each eXo service, so it is necessary for you to further understand about them.</para>
<para>This chapter includes the following main topics:</para>
<itemizedlist>
  <listitem>
	<para>
	  <emphasis role="bold"><link linkend="DEV.WorkWithApplications.ApplicationIntegration">Integrate an application</link> </emphasis>
	</para>
	<para>
	Instructions on how to add an application (especially a portlet) to your portal's paces.
		</para>
	  </listitem>
	  <listitem>
		<para>
	  <emphasis role="bold"><link linkend="DEV.WorkWithApplications.DevelopYourOwnApplications">Develop your own application</link> </emphasis>
		</para>
		<para>
	Instructions on how to develop a gadget for eXo Platform, and information about Portlet Bridges.
		</para>
	  </listitem>
	<listitem>
	<para>
	  <emphasis role="bold"><link linkend="DEV.ExtendeXoApplications">Extend eXo applications</link></emphasis>
	</para>
	<para>
	Concept and mechanism of UI Extension framework which allows the customization and extensibility of eXo applications through simple plugins.
	</para>
  </listitem>
	
	</itemizedlist>
</abstract>
{docbook}

h1. Integrate an application {anchor:id=DEV.WorkWithApplications.ApplicationIntegration}

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:

{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. |
| {{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|../../../reference/html/JCRReferenceGuide.html]. |

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Develop your own application|#DEV.WorkWithApplications.DevelopYourOwnApplications]
* [Extend eXo applications|#DEV.ExtendeXoApplications]

h1. Develop your own application {anchor:id=DEV.WorkWithApplications.DevelopYourOwnApplications}
{docbook}
<highlights>
        <itemizedlist>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithApplications.DevelopAGadgetForPlatform">Develop a gadget for eXo Platform</link>
            </para>
			<para>
			Introduction to the resources which can be shared for all gadgets and their categories, instructions on how to apply for a gadget and to customize the gadget thumbnail. 
			</para>
          </listitem>
          <listitem>
            <para>
              <link linkend="DEV.WorkWithApplications.PortletBridges">Portlet Bridges</link>
            </para>
			<para>
			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.
			</para>
          </listitem>
        </itemizedlist>
</highlights>
{docbook}

{docbook}
<para>
<prompt>
    <emphasis role="bold">See also</emphasis>
</prompt>
</para>
{docbook}
* [Integrate an application|#DEV.WorkWithApplications.ApplicationIntegration]
* [Extend eXo applications|#DEV.ExtendeXoApplications]

h2. Develop a gadget for eXo Platform {anchor:id=DEV.WorkWithApplications.DevelopAGadgetForPlatformRoleNotInToc}

{note}
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 the [Portlet development|../../../reference/html/chap-Reference_Guide-Portlet_development.html] and [Gadget development|../../../reference/html/chap-Reference_Guide-Gadget_development.html] sections.
{note}

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|../../../reference/html/chap-Reference_Guide-Gadget_development.html] and [Develop gadgets via a powerful web-based IDE of eXo Platform|../ide-user-guide/IDEdev.OperationWithGoogleGadget.html] sections.
{note}

h3. Resources {anchor:id=DEV.WorkWithApplications.DevelopAGadgetForPlatform.Resource}

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: 

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

h3. Apply for a gadget {anchor:id=DEV.WorkWithApplications.DevelopAGadgetForPlatform.ApplyForGadget}

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:

{code:xml}<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" width="80mm" fo:scalefit="1" html:scalefit="0"!

{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, and more) that are defined in the _gadget-common.css_.

{code: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" width="80mm" fo:scalefit="1" html:scalefit="0"!

h3. Customize the gadget thumbnail {anchor:id=DEV.WorkWithApplications.DevelopAGadgetForPlatform.CustomizeGadgetThumnail}

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. 

!images/gadget_thumbnail.png|align="center" width="150mm" fo:scalefit="1" html:scalefit="0"!

* 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-icon_80x80.png"/>.

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

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.

h1. Extend eXo applications {anchor:id=DEV.ExtendeXoApplications}

{include:document=Extend_eXo_applications.wiki|syntax=confluence/1.0}