GateIn Reference Guide

GateIn 3.2 has two different database dependencies. One is the identity service configuration, which depends on Hibernate. The other is the Java content repository (JCR) service, which depends on JDBC API and can integrate with any existing datasource implementation.

When you change the database configuration for the first time, GateIn will automatically generate the proper schema (assuming that the database user has the appropriate permissions).

GateIn 3.2 assumes the default encoding for your database is latin1. You may need to change this parameter for your database so that GateIn 3.2 works properly.

To configure the database used by JCR, edit the file:$JBOSS_HOME/server/default/conf/gatein/configuration.properties.

For Tomcat, the file is located at $TOMCAT_HOME/gatein/conf/configuration.properties.

Next, edit the values of driver, url, username and password with the values for your JDBC connection. To learn more, refer to your database JDBC driver documentation.

gatein.jcr.datasource.driver=org.hsqldb.jdbcDriver

gatein.jcr.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr_${name}

gatein.jcr.datasource.username=sa

gatein.jcr.datasource.password=

By default, the name of the database is "jdbcjcr_${name}" - ${name} should be a part of the database name, as it is dynamically replaced by the name of the portal container extension. For example, gatein-sample-portal.ear defines "sample-portal" as the container name and the default portal defines "portal" as the container name.

In case of HSQL, the databases are created automatically. For any other databases, you need to create a database named "jdbcjcr_portal" (and "jdbcjcr_sample-portal" if you have gatein-sample-portal.ear in $JBOSS_HOME/server/default/deploy). Note that some databases do not accept '-' in the database name, so you may have to remove $JBOSS_HOME/server/default/deploy/gatein-sample-portal.ear.

Make sure the user has rights to create tables on jdbcjcr_portal, and to update them as they will be automatically created during the first startup.

Also, add your database's JDBC driver into the classpath - you can put it in $JBOSS_HOME/server/default/lib (or $TOMCAT_HOME/lib, if you are running on Tomcat).

MySQL example:

Configure the JCR to store data in MySQL and assume that you created a user named "gateinuser" with a password "gateinpassword". Next, create a database mygateindb_portal (remember that portal is required), and assign the rights to create tables to the users.

Add the MySQL's JDBC driver to the classpath, and finally edit gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration to contain the following:

gatein.jcr.datasource.driver=com.mysql.jdbc.Driver
gatein.jcr.datasource.url=jdbc:mysql://localhost:3306/mygateindb${container.name.suffix}
gatein.jcr.datasource.username=gateinuser
gatein.jcr.datasource.password=gateinpassword

By default, users are stored in a database. To change the database where users are stored, you need to edit the file:

$JBOSS_HOME/server/default/conf/gatein/configuration.propertiesFor Tomcat, the file is located at $TOMCAT_HOME/gatein/conf/configuration.properties

You will find the same type of configuration as in jcr-configuration.xml:

gatein.idm.datasource.driver=org.hsqldb.jdbcDriver
gatein.idm.datasource.url=jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm_${name}
gatein.idm.datasource.username=sa
gatein.idm.datasource.password

GateIn 3.2 includes an e-mail sending service that needs to be configured before it can function properly. This service, for instance, is used to send emails to users who forgot their password or username.

The e-mail service can use any SMTP account configured in $JBOSS_HOME/server/default/conf/gatein/configuration.properties (or $TOMCAT_HOME/gatein/conf/configuration.properties if you are using Tomcat).

The relevant section looks like:

# EMail
gatein.email.smtp.username=
gatein.email.smtp.password=
gatein.email.smtp.host=smtp.gmail.com
gatein.email.smtp.port=465
gatein.email.smtp.starttls.enable=true
gatein.email.smtp.auth=true
gatein.email.smtp.socketFactory.port=465
gatein.email.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

It is preconfigured for GMail, so that any GMail account can easily be used (simply use the full GMail address with username and password.

In corporate environments, if you want to use your corporate SMTP gateway over SSL, like in the default configuration, configure a certificate truststore containing your SMTP server's public certificate. Depending on the key sizes, you may then also need to install Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for your Java Runtime Environment.

GateIn 3.2 provides robust skinning support for the entire portal User Interface (UI). This includes support for skinning all of the common portal elements and being able to provide custom skins and window decoration for individual portlets. It is designed to common graphic resource reuse and ease of development .

The complete skinning of a page can be decomposed into three main parts:

The GateIn 3.2 skin contains CSS styles for the portal's components but also shares components that may be reused in portlets. When GateIn 3.2 generates a portal page markup, it inserts the stylesheet links in the page's head tag.

There are two main types of CSS links that will appear in the head tag: a link to the portal skin CSS file and a link to the portlet skin CSS files.

In the code fragment below, you can see two types of links:

<head>
...
<!-- The portal skin -->
<link id="CoreSkin" rel="stylesheet" type="text/css" href="/eXoResources/skin/Stylesheet.css" />

<!-- The portlet skins -->
<link id="web_FooterPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet.css" />
<link id="web_NavigationPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UINavigationPortlet/DefaultStylesheet.css" />
<link id="web_HomePagePortlet" rel="stylesheet" type="text/css" href= "/portal/templates/skin/webui/component/UIHomePagePortlet/DefaultStylesheet.css" />
<link id="web_BannerPortlet" rel="stylesheet" type="text/css" href= "/web/skin/portal/webui/component/UIBannerPortlet/DefaultStylesheet.css" />
...
</head>

The skin service of GateIn 3.2 manages various types of skins. This service is reponsible for discovering and deploying the skins into the portal.

<gatein-resources>
  <portal-skin>
    <skin-name>MySkin</skin-name>
    <css-path>/skin/myskin.css</css-path>
    <overwrite>false</overwrite>
  </portal-skin>
</gatein-resources>

  <!-- window style -->
  <window-style>
    <style-name>MyThemeCategory</style-name>
    <style-theme>
      <theme-name>MyThemeBlue</theme-name>
    </style-theme>
    <style-theme>
      <theme-name>MyThemeRed</theme-name>
    </style-theme>
    ...
      

<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>*.css</url-pattern>
      </filter-mapping>

The default skin for GateIn 3.2 is located as part of the 01eXoResource.war. The main files associated with the skin are shown below:

WEB-INF/gatein-resources.xml
WEB-INF/web.xml
skin/Stylesheet.css

	gatein-resources.xml: defines the skin setup to use.
	web.xml: contains the resource filter and has the display-name set.
	Stylesheet.css: contains the CSS class definitions for this skin.

This chapter describes the portal lifecycle from the application server start to its stop and how requests are handled.

A portal instance is simply a web application deployed as a WAR in an application server. Portlets are also part of an enhanced WAR called a portlet application.

GateIn 3.2 does not require any particular setup for your portlet in most common scenarios and the web.xml file can remain without any GateIn 3.2 specific configuration.

During deployment, GateIn 3.2 will automatically and transparently inject a servlet into the portlet application to be able to interact with it. This feature is dependent on the underlying servlet container but will work out of the box on the proposed bundles.

The servlet is the main entry point for incoming requests, it also includes some init codes when the portal is launched. This servlet (org.gatein.wci.command.CommandServlet) is automatically added during deployment and mapped to /tomcatgateinservlet.

This is equivalent to adding the following to web.xml.

<servlet>
  <servlet-name>TomcatGateInServlet</servlet-name>
  <servlet-class>org.gatein.wci.command.CommandServlet</servlet-class>
  <load-on-startup>0</load-on-startup>
</servlet>
  
<servlet-mapping>
  <servlet-name>TomcatGateInServlet</servlet-name>
  <url-pattern>/tomcatgateinservlet</url-pattern>
</servlet-mapping>

It is possible to filter on the CommandServlet by filtering the URL pattern used by the Servlet mapping.

The example below would create a servlet filter that calculates the time of execution of a portlet request.

The filter class:

package org.example;

import java.io.IOException;

import javax.servlet.FilterChain;
import javax.servlet.FilterConfig;
import javax.servlet.ServletException;
import javax.servlet.ServletRequest;
import javax.servlet.ServletResponse;

public class MyFilter implements javax.servlet.Filter {

  public void doFilter(ServletRequest request, ServletResponse response,
      FilterChain chain) throws IOException, ServletException
  {
    long beforeTime = System.currentTimeMillis();
    chain.doFilter(request, response);
    long afterTime = System.currentTimeMillis();
    System.out.println("Time to execute the portlet request (in ms): " + (afterTime - beforeTime));
  }

  public void init(FilterConfig config) throws ServletException
  {
  }

  public void destroy()
  {
  }

}

The Java EE web application configuration file (web.xml) of the portlet on which we want to know the time to serve a portlet request. As mentioned above, GateIn 3.2 does not require anything special to be included, only the URL pattern to set has to be known.

<?xml version="1.0"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.5">
        
  <filter>
    <filter-name>MyFilter</filter-name>
    <filter-class>org.example.MyFilter</filter-class>        
  </filter>

  <filter-mapping>
    <filter-name>MyFilter</filter-name>
    <url-pattern>/tomcatgateinservlet</url-pattern>
    <dispatcher>INCLUDE</dispatcher>  
  </filter-mapping>    
    
</web-app>

GateIn 3.2 default homepage URL is http://{hostname}:{port}/portal/. There may be multiple independent portals deployed in parallel at any given time, each of which has its root context (i.e.: http://{hostname}:{port}/sample-portal/). Each portal is internally composed of one or more 'portals'. It is required to have at least one such portal - the default one is called 'classic'. When accessing the default homepage URL of GateIn 3.2, you are automatically redirected to the 'classic' portal. The default portal performs another important task. When starting up GateIn 3.2 for the first time, its JCR database will be empty (that's where portals keep their runtime-configurable settings). It is the default portal used to detect this, and to trigger automatic data initialization.

The following example configuration can be found at: "02portal.war:/WEB-INF/conf/portal/portal-configuration.xml".

<component>

    <key>org.exoplatform.portal.config.UserPortalConfigService</key>

    <type>org.exoplatform.portal.config.UserPortalConfigService</type>

    <component-plugins>           

     <component-plugin>

       <name>new.portal.config.user.listener</name>

       <set-method>initListener</set-method>

       <type>org.exoplatform.portal.config.NewPortalConfigListener</type>

       <description>this listener init the portal configuration</description>

       <init-params>

         <value-param>

           <name>default.portal</name>

           <description>The default portal for checking db is empty or not</description>

           <value>classic</value>

         </value-param> 

         ...

       </init-params>

     </component-plugin>

    </component-plugins> 

  </component>

In this example, the classic portal has been set as the default.

The default permission configuration for the portal is defined through org.exoplatform.portal.config.UserACL component configuration in the file 02portal.war:/WEB-INF/conf/portal/portal-configuration.xml.

It defines 8 permissions types:

<component>
  <key>org.exoplatform.portal.config.UserACL</key>
  <type>org.exoplatform.portal.config.UserACL</type>   
  <init-params>      
    <value-param>
      <name>super.user</name>
      <description>administrator</description>
      <value>root</value>     
    </value-param>
      
    <value-param>
      <name>portal.creator.groups</name>
      <description>groups with membership type have permission to manage portal</description>
      <value>*:/platform/administrators,*:/organization/management/executive-board</value>     
    </value-param>
      
    <value-param>
      <name>navigation.creator.membership.type</name>
      <description>specific membership type have full permission with group navigation</description>
      <value>manager</value>     
    </value-param>
    <value-param>
      <name>guests.group</name>
      <description>guests group</description>
      <value>/platform/guests</value>     
    </value-param>     
    <value-param>
      <name>access.control.workspace</name>
      <description>groups with memberships that have the right to access the User Control Workspace</description>
      <value>*:/platform/administrators,*:/organization/management/executive-board</value>     
    </value-param>           
  </init-params>   
</component>

When creating the custom portals and portal extensions, it is possible to override the default configuration by using org.exoplatform.portal.config.PortalACLPlugin, configuring it as an external-plugin of org.exoplatform.portal.config.UserACL service:

<external-component-plugins>
    <target-component>org.exoplatform.portal.config.UserACL</target-component>
    <component-plugin>
      <name>addPortalACLPlugin</name>
      <set-method>addPortalACLPlugin</set-method>
      <type>org.exoplatform.portal.config.PortalACLPlugin</type>
      <description>setting some permission for portal</description>
      <init-params>     
        <values-param>
          <name>access.control.workspace.roles</name>
          <value>*:/platform/administrators</value>
          <value>*:/organization/management/executive-board</value>       
        </values-param>
        <values-param>
          <name>portal.creation.roles</name>
          <value>*:/platform/administrators</value>
          <value>*:/organization/management/executive-board</value>      
        </values-param>
      </init-params>
    </component-plugin>
  </external-component-plugins>

There are three navigation types available to portal users:

These navigations are configured using the standard XML syntax in the file; "02portal.war:/WEB-INF/conf/portal/portal-configuration.xml".

<component>

   <key>org.exoplatform.portal.config.UserPortalConfigService</key>

   <type>org.exoplatform.portal.config.UserPortalConfigService</type>

   <component-plugins>

      <component-plugin>

         <name>new.portal.config.user.listener</name>

         <set-method>initListener</set-method>

         <type>org.exoplatform.portal.config.NewPortalConfigListener

      </type>

         <description>this listener init the portal configuration

      </description>

         <init-params>

            <value-param>

               <name>default.portal</name>

               <description>The default portal for checking db is empty or not</description>

               <value>classic</value>

            </value-param>

            <value-param>

               <name>page.templates.location</name>

               <description>the path to the location that contains Page templates</description>

               <value>war:/conf/portal/template/pages</value>

            </value-param>

            <value-param>

               <name>override</name>

               <description>The flag parameter to decide if portal metadata is overriden on restarting server

            </description>

               <value>false</value>

            </value-param>

            <object-param>

               <name>site.templates.location</name>

               <description>description</description>

               <object type="org.exoplatform.portal.config.SiteConfigTemplates">

                  <field name="location">

                     <string>war:/conf/portal</string>

                  </field>

                  <field name="portalTemplates">

                     <collection type="java.util.HashSet">

                        <value><string>basic</string></value>

                        <value><string>classic</string></value>

                     </collection>

                  </field>

                  <field name="groupTemplates">

                     <collection type="java.util.HashSet">

                        <value><string>group</string></value>

                     </collection>

                  </field>

                  <field name="userTemplates">

                     <collection type="java.util.HashSet">

                        <value><string>user</string></value>

                     </collection>

                  </field>

               </object>

            </object-param>

            <object-param>

               <name>portal.configuration</name>

               <description>description</description>

               <object type="org.exoplatform.portal.config.NewPortalConfig">

                  <field name="predefinedOwner">

                     <collection type="java.util.HashSet">

                        <value><string>classic</string></value>

                     </collection>

                  </field>

                  <field name="ownerType">

                     <string>portal</string>

                  </field>

                  <field name="templateLocation">

                     <string>war:/conf/portal/</string>

                  </field>

                  <field name="importMode">

                     <string>conserve</string>

                  </field>

               </object>

            </object-param>

            <object-param>

               <name>group.configuration</name>

               <description>description</description>

               <object type="org.exoplatform.portal.config.NewPortalConfig">

                  <field name="predefinedOwner">

                     <collection type="java.util.HashSet">

                        <value><string>/platform/administrators</string></value>

                        <value><string>/platform/users</string></value>

                        <value><string>/platform/guests</string></value>

                        <value><string>/organization/management/executive-board</string></value>

                     </collection>

                  </field>

                  <field name="ownerType">

                     <string>group</string>

                  </field>

                  <field name="templateLocation">

                     <string>war:/conf/portal</string>

                  </field>

                  <field name="importMode">

                     <string>conserve</string>

                  </field>

               </object>

            </object-param>

            <object-param>

               <name>user.configuration</name>

               <description>description</description>

               <object type="org.exoplatform.portal.config.NewPortalConfig">

                  <field name="predefinedOwner">

                     <collection type="java.util.HashSet">

                        <value><string>root</string></value>

                        <value><string>john</string></value>

                        <value><string>mary</string></value>

                        <value><string>demo</string></value>

                        <value><string>user</string></value>

                     </collection>

                  </field>

                  <field name="ownerType">

                     <string>user</string>

                  </field>

                  <field name="templateLocation">

                     <string>war:/conf/portal</string>

                  </field>

                  <field name="importMode">

                     <string>conserve</string>

                  </field>

               </object>

            </object-param>

         </init-params>

      </component-plugin>

   </component-plugins>

</component>

This XML configuration defines where in the portal's war to look for configuration, and which portals, groups, and user specific views to include in portal/group/user navigation. Those files will be used to create an initial navigation when the portal is launched in the first time. That information will then be stored in the JCR content repository, and can then be modified and managed from the portal UI.

Each portal, groups and users navigation is indicated by a configuration paragraph, for example:

<object-param>
   <name>portal.configuration</name>
   <description>description</description>
   <object type="org.exoplatform.portal.config.NewPortalConfig">
      <field name="predefinedOwner">
         <collection type="java.util.HashSet">
            <value><string>classic</string></value>
         </collection>
      </field>
      <field name="ownerType">
         <string>portal</string>
      </field>
      <field name="templateLocation">
         <string>war:/conf/portal/</string>
      </field>
      <field name="importMode">
         <string>conserve</string>
      </field>
   </object>
</object-param>

	predefinedOwner define the navigation owner, portal will look for the configuration files in folder with this name, if there is no suiable folder, a default portal will be created with name is this value.
	ownerType define the type of portal navigation. It may be a portal, group or user
	templateLocation the classpath where contains all portal configuration files
	importMode The mode for navigation import. There are 4 types of import mode: conserve: Import data when it does not exist, otherwise do nothing. insert: Import data when it does not exist, otherwise performs a strategy that adds new data only. merge: Import data when it does not exist, update data when it exists. rewrite: Overwrite data whatsoever.

Base on these parameters, portal will look for the configuration files and create a relevant portal navigation, pages and data import strategy. The portal configuration files will be stored in folders with path look like {templateLocation}/{ownerType}/{predefinedOwner}, all navigations are defined in the navigation.xml file, pages are defined in pages.xml and portal configuration is defined in {ownerType}.xml. For example, with the above configuration, prtal will look for all configuration files from war:/conf/portal/portal/classic path.

The portal navigation incorporates the pages that can be accessed even when the user is not logged in assuming the applicable permissions allow the public access). For example, several portal navigations are used when a company owns multiple trademarks, and sets up a website for each of them.

The classic portal is configured by four XML files in the 02portal.war:/WEB-INF/conf/portal/portal/classic directory:

Group navigations are dynamically added to the user navigation at login. This allows users to see the menu of all pages assigned to any groups they belong to.

The group navigation menu is configured by three XML files (navigation.xml, pages.xml and portlet-preferences.xml). The syntax used in these files is the same as those covered in Section 3.5.2, “Portal Navigation”.

They are also located in the {templateLocation}/{ownerType}/{predefinedOwner} directory with ownerType is group and predefinedOwner is the path to the group. For example, portal.war/WEB-INF/conf/portal/group/platform/administrators/.

User navigation is the set of nodes and pages that are owned by the user. They are part of the user's dashboard.

Three files configure the user navigation (navigation.xml, pages.xml and portlet-preferences.xml). They are located in the {templateLocation}/{ownerType}/{predefinedOwner} directory with ownerType is user and predefinedOwner is username that want to create the navigation. For example, if administrator want to create navigation for user root, he has to locate the configuration files in portal.war/WEB-INF/conf/portal/user/root

In the Portal extension mechanism, developers can define an extension that Portal data can be customized by configurations in the extension. There are several cases which an extension developer wants to define how to customize the Portal data, for example modifying, overwriting or just inserting a bit into the data defined by the portal. Therefore, GateIn also defines several modes for each case and the only thing which a developer has to do is to clarify the usecase and reasonably configure extensions.

This section shows you how data are changes in each mode.

All GateIn 3.2 applications contain property files for various languages. They are packaged with the portlets applications in a WEB-INF/classes/locale/ directory.

These files are located in the classes folder of the WEB-INF directory to be loaded by the ClassLoader.

All resource files are in a subfolder named locale.

For example, the translations for the NavigationPortlet are located in web.war/WEB-INF/classes/locale/portlet/portal.

NavigationPortlet_de.properties
NavigationPortlet_en.properties
NavigationPortlet_es.properties
NavigationPortlet_fr.properties
NavigationPortlet_nl.properties
NavigationPortlet_ru.properties
NavigationPortlet_uk.properties
NavigationPortlet_ar.xml

Those files contain typical key=value Java EE properties. For example, the French one:

javax.portlet.title=Portlet Navigation

There are also properties files in the portal itself. They form the portal resource bundle.

From a portlet, you can then access translations from the portlet itself or shared at the portal level, both are aggregated when you need them.

Various languages are available in the portal package. The configuration below will define which languages shown in the "Change Language" section and made available to users.

The 02portal.war:/WEB-INF/conf/common/common-configuration.xml file of your installation contains the following section:

<component>
  <key>org.exoplatform.services.resources.LocaleConfigService</key>
  <type>org.exoplatform.services.resources.impl.LocaleConfigServiceImpl</type>
  <init-params>
    <value-param>
      <name>locale.config.file</name>
      <value>war:/conf/common/locales-config.xml</value>
    </value-param>
  </init-params>
</component>

This configuration points to the locale configuration file.

The locale configuration file (02portal.war:/WEB-INF/conf/common/locales-config.xml) contains the following code:

<?xml version="1.0" encoding="UTF-8"?>
<locales-config>
  <locale-config>
    <locale>en</locale>
    <output-encoding>UTF-8</output-encoding>
    <input-encoding>UTF-8</input-encoding>
    <description>Default configuration for english locale</description>
  </locale-config>
 
  <locale-config>
    <locale>fr</locale>
    <output-encoding>UTF-8</output-encoding>
    <input-encoding>UTF-8</input-encoding>
    <description>Default configuration for the french locale</description>
  </locale-config>
 
  <locale-config>
    <locale>ar</locale>
    <output-encoding>UTF-8</output-encoding>
    <input-encoding>UTF-8</input-encoding>
    <description>Default configuration for the arabic locale</description>
    <orientation>rt</orientation>
  </locale-config>
</locales-config>

	locale The locale has to be defined, such as http://ftp.ics.uci.edu-pub-ietf-http-related-iso639.txt. In this example, "ar" is Arabic.
	output-encoding deals with the character encoding. It is recommended that UTF-8 be used.
	input-encoding In the Java implementation, the encoding parameters will be used for the request response stream. The input-encoding parameter will be used for requesting setCharacterEncoding(..).
	description Description for the language
	orientation The default orientation of text and images is Left-To-Right. GateIn 3.2 supports Right-To-Left orientation. Modifying the text orientation is explained in Section 3.8, “RTL (Right To Left) Framework”.

The resource bundle service is configured in: 02portal.war:/WEB-INF/conf/common/common-configuration.xml:

<component>
  <key>org.exoplatform.services.resources.ResourceBundleService</key>
  <type>org.exoplatform.services.resources.impl.SimpleResourceBundleService</type>
  <init-params>
    <values-param>
      <name>classpath.resources</name>
      <description>The resources  that start with the following package name should be load from file system</description>
      <value>locale.portlet</value>      
    </values-param>      
    <values-param>
      <name>init.resources</name>
      <description>Initiate the following resources during the first launch</description>
      <value>locale.portal.expression</value>
      <value>locale.portal.services</value>
      <value>locale.portal.webui</value>
      <value>locale.portal.custom</value>
      <value>locale.navigation.portal.classic</value>
      <value>locale.navigation.group.platform.administrators</value>
      <value>locale.navigation.group.platform.users</value>
      <value>locale.navigation.group.platform.guests</value>
      <value>locale.navigation.group.organization.management.executive-board</value>               
    </values-param>      
    <values-param>
      <name>portal.resource.names</name>
      <description>The properties files of  the portal ,  those file will be merged 
        into one ResoruceBundle properties </description>
      <value>locale.portal.expression</value>
      <value>locale.portal.services</value>
      <value>locale.portal.webui</value>
      <value>locale.portal.custom</value>        
    </values-param>      
  </init-params>
</component>

	classpath.resources are discussed in the later section.
	init.resources initiates resources related to portal, group, user resource bundle.
	portal.resource.names defines all resources that belong to the Portal Resource Bundle. These resources are merged into a single resource bundle which is accessible from anywhere in GateIn 3.2. All these keys are located in the same bundle, which is separated from the navigation resource bundles.

There is a resource bundle for each navigation. A navigation can exist for user, groups, and portal.

The previous example shows bundle definitions for the navigation of the classic portal and of four different groups. Each of these resource bundles occupies a different sphere, they are independent of each other and they are not included in the portal.resource.names parameter.

The properties for a group must be in the WEB-INF/classes/locale/navigation/group/ folder. /WEB-INF/classes/locale/navigation/group/organization/management/executive-board_en.properties, for example.

The folder and file names must correspond to the group hierarchy. The group name "executive-board" is followed by the iso 639 code.

For each language defined in LocalesConfig must have a resource file defined. If the name of a group is changed the name of the folder and/or files of the correspondent navigation resource bundles must also be changed.

Content of executive-board_en.properties:

organization.title=Organization
organization.newstaff=New Staff
organization.management=Management

This resource bundle is only accessible for the navigation of the organization.management.executive-board group.

Portlets are independent applications and deliver their own resource files.

All shipped portlet resources are located in the locale/portlet subfolder. The ResourceBundleService parameter classpath.resources defines this subfolder.

See the portlet specification for more details about the portlet internationalization.

 javax.portlet.title=Breadcrumbs Portlet
 javax.portlet.short-title=Breadcrumbs
 javax.portlet.keywords=Breadcrumbs, Breadcrumb

When choosing a language as on the screenshot above, the user is presented with a list of languages on the left side in the current chosen language and on the right side, the same language translated into its own language. Those texts are obtained from the JDK API java.util.Locale.getDisplayedLanguage() and java.util.Locale.getDisplayedCountry() (if needed) and all languages may not be translated and can also depend on the JVM currently used. It is still possible to override those values by editing the locale.portal.webui resource bundle, to do so edit the file gatein.ear/02portal.war/WEB-INF/classes/locale/portal/webui_xx_yy.properties where xx_yy represents the country code of the language in which you want to translate a particular language. In that file, add or modify a key such as Locale.xx_yy with the value being the translated string.

              Locale.zh_TW=Chinois traditionnel
           

Orientation is defined by implicit variables in the Groovy binding context:

The skin service handles stylesheet rewriting to accommodate the orientation. It works by appending -lt or -rt to the stylesheet name.

For instance: /web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet-rt.css will return the same stylesheet as /web/skin/portal/webui/component/UIFooterPortlet/DefaultStylesheet.css but processed for the RT orientation. The -lt suffix is optional.

Stylesheet authors can annotate their stylesheet to create content that depends on the orientation.

float: left; /* orientation=lt */
float: right; /* orientation=rt */
font-weight: bold;
text-align: center;
white-space: nowrap;

float: left; /* orientation=lt */
font-weight: bold;
text-align: center;
white-space: nowrap;

 
float: right; /* orientation=rt */
font-weight: bold;
text-align: center;
white-space: nowrap;

color: white;
line-height: 24px;
padding: 0px 5px 0px 0px; /* orientation=lt */
padding: 0px 0px 0px 5px; /* >orientation=rt */

 
color: white;
line-height: 24px;
padding: 0px 5px 0px 0px; /* orientation=lt */

 
color: white;
line-height: 24px;
padding: 0px 0px 0px 5px; /* orientation=rt */

Sometimes, it is necessary to create the RT version of an image that will be used from a template or from a stylesheet. However, symmetric images can be automatically generated avoiding the necessity to create a mirrored version of an image and furthermore avoiding maintenance cost.

The web resource filter uses the same naming pattern as the skin service. When an image ends with the -rt suffix, the portal will attempt to locate the original image and create a mirror of it.

For instance: requesting the image /GateInResources/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle-rt.gif returns a mirror of the image /GateInResources/skin/DefaultSkin/webui/component/UITabSystem/UITabs/background/NormalTabStyle.gif.

Here is an example combining stylesheet and images:

line-height: 24px; 
background: url('background/NavigationTab.gif') no-repeat right top; /* orientation=lt */
background: url('background/NavigationTab-rt.gif') no-repeat left top; /* orientation=rt */
padding-right: 2px; /* orientation=lt */
padding-left: 2px; /* orientation=rt */

The eXo.core.I18n object provides the following parameters for orientation:

Resource bundles are usually stored in property files. However, as property files are plain files, issues with the encoding of the file may arise. The XML resource bundle format has been developed to provide an alternative to property files.

The XML format is very simple and has been developed based on the DRY (Don't Repeat Yourself) principle. The resource bundle keys are hierarchically defined and we can leverage the hierarchic nature of the XML for that purpose. Here is an example of turning a property file into an XML resource bundle file:

UIAccountForm.tab.label.AccountInputSet = ...
UIAccountForm.tab.label.UIUserProfileInputSet = ...
UIAccountForm.label.Profile = ...
UIAccountForm.label.HomeInfo= ...
UIAccountForm.label.BusinessInfo= ...
UIAccountForm.label.password= ...
UIAccountForm.label.Confirmpassword= ...
UIAccountForm.label.email= ...
UIAccountForm.action.Reset= ...

<?xml version="1.0" encoding="UTF-8"?>
<bundle>
  <UIAccountForm>
    <tab>
      <label>
        <AccountInputSet>...</AccountInputSet>
        <UIUserProfileInputSet>...</UIUserProfileInputSet>
      </label>
    </tab>
    <label>
      <Profile>...</Profile>
      <HomeInfo>...</HomeInfo>
      <BusinessInfo>...</BusinessInfo>
      <password>...</password>
      <Confirmpassword>...</Confirmpassword>
      <email>...</email>
    </label>
    <action>
      <Reset>...</Reset>
    </action>
  </UIAccountForm>
</bundle>

To be loaded by the portal at runtime (actually the resource bundle service), the name of the file must be the same as a property file and it must use the .xml suffix.

For example, for the Account Portlet to be displayed in Arabic, the resource bundle would be AccountPortlet_ar.xml rather than AccountPortlet_ar.properties.

JavaScript Inter Application Communication is designed to allow applications within a page to exchange data. This library is made for broadcasting messages on topic.

It is based on 3 functions:

A subscription to a topic will receive any subtopic messages. For example, the application subscribed to "/eXo/application" will receive messages sent on the "/eXo/application/map" topic. A message sent on "/eXo" would not be received.

The Inter Application Communication library is found in 01eXoResources.war:/javascript/eXo/core/Topic.js

/**
 * publish is used to publish an event to the other subscribers to the given channels
 * @param {Object} senderId is a string that identify the sender
 * @param {String} topic is the topic that the message will be published
 * @param {Object} message is the message that's going to be delivered to the subscribers to the topic
 */
Topic.prototype.publish = function(/*Object*/ senderId, /*String*/ topicName, /*Object*/ message ) { ... }

/**
 * isSubscribed is used to check if a function receive the events from a topic
 * @param {String} topic The topic.
 * @param {Function} func is the name of the function of obj to call when a message is received on the topic
 */
Topic.prototype.isSubscribed = function(/*String*/ topic, /*Function*/ func) { ... }

/**
 * subscribe is used to subscribe a callback to a topic
 * @param {String} topic is the topic that will be listened
 * @param {Function} func is the name of the function of obj to call when a message is received on the topic
 * 
 * func is a function that take a Object in parameter. the event received have this format:
 * {senderId:senderId, message:message, topic: topic}
 *
 */
Topic.prototype.subscribe = function(/*String*/ topic, /*Function*/ func) { ... }

/**
 * unsubscribe is used to unsubscribe a callback to a topic
 * @param {String} topic is the topic
 * @param {Object} id is the id of the listener we want to unsubscribe
 */
Topic.prototype.unsubscribe = function(/*String*/ topic, /*Object*/ id) { ... }

Topic.prototype.initCometdBridge = function() { ... }

The three messaging functions require particular objects and definitions in their syntax:

<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet" %>
<portlet:defineObjects/>
<div>
  <p>
    Received messages:
    <div id="received_<portlet:namespace/>">
         
    </div>
  </p>
   
  <p>
    Send message:
    <input type="text" id="msg_<portlet:namespace/>"/> <a href="#" onclick="send_<portlet:namespace/>();">send</a>
  </p>
</div>

<script type="text/javascript">
   
  Function.prototype.bind = function(object) {
    var method = this;
      return function() {
      method.apply(object, arguments);
    }
  }
   
  function send_<portlet:namespace/>() {
    var msg = document.getElementById("msg_<portlet:namespace/>").value;
    eXo.core.Topic.publish("<portlet:namespace/>", "/demo", msg);
  }
   
  function Listener_<portlet:namespace/>(){
      
  }
   
  Listener_<portlet:namespace/>.prototype.receiveMsg = function(event) {
    document.getElementById("received_<portlet:namespace/>").innerHTML = 
      document.getElementById("received_<portlet:namespace/>").innerHTML + "<br />* " + 
      event.senderId + ": " + event.message;
  }
   
  function init_<portlet:namespace/>() {
    var listener_<portlet:namespace/> = new Listener_<portlet:namespace/>();
    eXo.core.Topic.subscribe("/demo", listener_<portlet:namespace/>.receiveMsg.bind(listener_<portlet:namespace/>));
  }
   
  init_<portlet:namespace/>();
</script>

The service is defined by the class: org.exoplatform.upload.UploadService;

This can be configured with the following xml code:

<component>
   <type>org.exoplatform.upload.UploadService</type>
     <init-params>
       <value-param>
        <name>upload.limit.size</name>
        <description>Maximum size of the file to upload in MB</description>
        <value>10</value>
      </value-param>
    </init-params>  
  </component>

This code allows for a default upload size limit for the service to be configured. The value unit is in MegaBytes.

This limit will be used by default by all applications if no application-specific limit is set. Setting a different limit for applications is discussed in a later section.

If the value is set to 0, the upload size is unlimited.

The loading mask layer is deployed after an ajax-call. It aims at blocking the GUI to prevent further user actions until the the ajax-request has been completed.

However, the mask layer may need to be deactivated in instances where the portal requires user instructions before the previous instructions have been carried out.

The GUI will be blocked to ensure that the user can only request one action at one time and while the request seems to be synchronous, all ajax requests are always asynchronous. For further information, refer to Section 3.12.2, “Synchronous issue”.

Most web browsers support ajax requests in two modes: Synchronous and Asynchronous. This mode is specified with a boolean bAsync parameter.

var bAsync = false; // Synchronous
request.open(instance.method, instance.url, bAsync);

However, to work with browsers that do not support the Synchronous requests, bAsync is always set to true (Ajax request will always be asynchronous).

// Asynchronous request
request.open(instance.method, instance.url, true);

The navigation controller is a major enhancement of GateIn that has several goals:

The navication controller implies a migration of the client code that is coupled to several internal APIs of GateIn. The major impact is related to anything dealing with URL:

String uri = Util.getPortalRequestContext().getPortalURI() + "home";

PortalURL nodeURL = nodeurl();
NavigationResource resource = new NavigationResource(SiteType.PORTAL, pcontext.getPortalOwner(), "home");
String uri = nodeURL.setResource(resource).toString();

UserNode node = ...;
String uri = Util.getPortalRequestContext().getPortalURI() + node.getURI()";

UserNode node = ...;
PortalURL nodeURL = nodeurl();
String uri = nodeURL.setNode(node).toString();

<controller>
  ...
  <route path="/">
    <route-param qname="gtn:handler">
      <value>default</value>
    </route-param>
  </route>
</controller>

<route path="/{gtn:path}">
  <route-param qname="gtn:handler">
    <value>staticResource</value>
  </route-param>
  <path-param encoding="preserve-path" qname="gtn:path">
    <pattern>.*\.(jpg|png|gif|ico|css)</pattern>
  </path-param>
</route>

<servlet-mapping>
  <servlet-name>default</servlet-name>
  <url-pattern>*.jpg</url-pattern>
</servlet-mapping>
...

<servlet>
  <servlet-name>DoLoginServlet</servlet-name>
  <servlet-class>org.exoplatform.web.login.DoLoginServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>DoLoginServlet</servlet-name>
  <url-pattern>/dologin</url-pattern>
</servlet-mapping>

<servlet-mapping>
   <servlet-name>portal</servlet-name>
   <url-pattern>/</url-pattern>
</servlet-mapping>

<security-constraint>
  <web-resource-collection>
    <web-resource-name>user authentication</web-resource-name>
      <url-pattern>/dologin</url-pattern>
      <url-pattern>/standalone/*</url-pattern>
      <url-pattern>/groups/*</url-pattern>
      <url-pattern>/users/*</url-pattern>
...
  </web-resource-collection>
</security-constraint>

<welcome-file-list>
  <welcome-file>/index.jsp</welcome-file>
</welcome-file-list>

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.

4.1.1.1. 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:

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 .

4.1.2.1. Deploying your first Portlet

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.

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

   

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

4.1.2.1.3. 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 GenericPortletrender 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.

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

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

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

2. Execute mvn package in this directory.

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

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

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

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

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

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

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 three steps in setting up a portlet filter:

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.

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>

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

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

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

Modify it from the Web where the Gadget was imported: