GateIn Reference Guide

GateIn 3.2 has two different database dependencies. One is the identity service configuration, which depends on Hibernate. The other is 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 in order for GateIn 3.2 to work properly.

To configure the database used by JCR you will need to edit the file:

$JBOSS_HOME/server/default/conf/gatein/configuration.properties

For Tomcat, the file is located at

$TOMCAT_HOME/gatein/conf/configuration.properties

And edit the values of driver, url, username and password with the values for your JDBC connection (please, 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 instance, gatein-sample-portal.ear defines "sample-portal" as container name and the default portal defines "portal" as container name).

In the case of HSQL the databases are created automatically. For any other database you will 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 don't 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:

Let's configure our JCR to store data in MySQL. Let's pretend we have a user named "gateinuser" with a password "gateinpassword". We would create a database "mygateindb_portal" (remember that _portal is required), and assign our user the rights to create tables.

Then we need to add 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 in which to store users, you will need to edit the file:

$JBOSS_HOME/server/default/conf/gatein/configuration.properties

For Tomcat, the file is located at

$TOMCAT_HOME/gatein/conf/configuration.properties

You will find the same kind 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 e-mails 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 as username, and fill-in the password.

In corporate environments you will want to use your corporate SMTP gateway. When using it over SSL, like in default configuration, you may need to 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 default run on HTTP mode. However, for security purpose, you can config GateIn to run on HTTPS mode. This section show you how to config GateIn with HTTPS mode.

If you haven't your own X.509 certificate, you can make a simple certificate using keytool command:

keytool -genkey -alias serverkeys -keyalg RSA -keystore server.keystore -storepass 123456 -keypass 123456 -dname "CN=localhost, 		OU=MYOU, O=MYORG, L=MYCITY, ST=MYSTATE, C=MY"

Now, your key is stored in server.keystore

You need to import your key into the Sun JDK keystore (This is required to help running gadget features)

keytool -importkeystore -srckeystore server.keystore -destkeystore $JAVA_HOME/jre/lib/security/cacerts

Edit server.xml from jboss/server/<NAME>/deploy/jbossweb.sar folder. Comment lines:

<Connector protocol="HTTP/1.1" port="8080" address="${jboss.bind.address}" 
		       connectionTimeout="20000" redirectPort="8443" />

Uncomment lines and change keystoreFile and keystorePass to values of your key:

<Connector protocol="HTTP/1.1" SSLEnabled="true" 
		   port="8443" address="${jboss.bind.address}"
		   scheme="https" secure="true" clientAuth="false" 
		   keystoreFile="$JAVA_HOME/jre/lib/security/cacerts"
		   keystorePass="123456" sslProtocol = "TLS" />

Edit server.xml from tomcat/conf folder. Comment lines:

<Connector port="8080" protocol="HTTP/1.1" 
		maxThreads="150" connectionTimeout="20000" 
		redirectPort="8443" URIEncoding="UTF-8"
		emptySessionPath="true"/>

Uncomment lines and add keystoreFile and keystorePass values:

<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
		maxThreads="150" scheme="https" secure="true"
		clientAuth="false" sslProtocol="TLS" 
		keystoreFile="$JAVA_HOME/jre/lib/security/cacerts"
		keystorePass="123456" />

Restart GateIn. If your configuration is correct, you can access to GateIn via address: https://<ServerAddress>:8443/portal

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 as well as being able to provide custom skins and window decoration for individual portlets. All of this designed with common graphic resource reuse and ease of development in mind.

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

A 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 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 the 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 is a GateIn 3.2 service which manages the various types of skins. It 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 is show below:

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

This chapter describes the portal lifecycle from the application server start to its stop as well as 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 doesn't 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 code 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 into 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 nothing specific to GateIn 3.2 needs 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 home page 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, what we again call 'portals'. There needs to be at least one such portal - the default one is called 'classic'. When accessing GateIn 3.2 default home page URL, you are automatically redirected to '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's the default portal that's 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 custom portals and portal extensions it's 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 types of navigation available to portal users:

These navigations are configured using 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> 

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

               <value><string>webos</string></value>

             </collection>

           </field>

           <field  name="ownerType"><string>portal</string></field>

           <field  name="templateLocation"><string>war:/conf/portal</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> 

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

             </collection>

           </field>

           <field  name="ownerType"><string>user</string></field>

           <field  name="templateLocation"><string>war:/conf/portal</string></field> 

         </object>

       </object-param>

     </init-params>

   </component-plugin>

</component-plugins>

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

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

The classic portal is configured by four XML files in 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 in the menu all the 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 located in portal.war/WEB-INF/conf/portal/group/group-name-path/ directory (For example; portal.war/WEB-INF/conf/portal/group/platform/administrators/).

User navigation is the set of nodes and pages that are owned by a 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 directory "portal.war/WEB-INF/conf/portal/users/{userName}".

This directory also contains a gadgets.xml file (formerly called widgets.xml). This file defines the gadgets located in the user's workspace.

The user's workspace is located at the left hand side of the page and access is restricted to some privileged users, see Section 6.1, “Predefined User Configuration”

<?xml version="1.0" encoding="ISO-8859-1"?>

<widgets>

  <owner-type>user</owner-type>

  <owner-id>root</owner-id>

 

  <container id="Information">

    <name>Information</name>

    <description>Information's Description</description>

    <application>

      <instance-id>user#root:/GateInWidgetWeb/WelcomeWidget/WelcomeWidget1</instance-id>

      <application-type>GateInWidget</application-type>

    </application>

      

    <application>

      <instance-id>user#root:/GateInWidgetWeb/StickerWidget/StickerWidget</instance-id>

      <application-type>GateInWidget</application-type> 

    </application>

    

    <application>

      <instance-id>user#root:/GateInWidgetWeb/InfoWidget/InfoWidget1</instance-id>

      <application-type>GateInWidget</application-type>

    </application>

  </container>

  

  <container id="Calendar">

    <name>Calendar</name>

    <description>Calendar's Description</description>

    <application>

      <instance-id>user#root:/GateInWidgetWeb/CalendarWidget/CalendarWidget</instance-id>

      <application-type>GateInWidget</application-type> 

    </application>

  </container> 

 

</widgets>

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, so as to be loaded by the ClassLoader.

All resource files are in a subfolder named locale.

For instance; 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

Inside those file are 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 are 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>

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>

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

Customization is achieved by using LocalePolicy API, which is a simple API consisting of one interface, and one class:

LocalePolicy interface defines a single method that’s invoked on the installed LocalePolicy service implementation:

public interface LocalePolicy
{
   public Locale determineLocale(LocaleContextInfo localeContext);
}
         

Locale returned by determineLocale() method is the Locale that will be returned to portlets when they call javax.portlet.PortletRequest.getLocale() method.

The returned Locale has to be one of the locales supported by portal, otherwise it will fallback to portal-default Locale.

The supported locales are listed in gatein.ear/02portal.war/WEB-INF/conf/common/locales-config.xml file as described in Section 3.6.2, “Locales configuration” .

The determineLocale() method takes a parameter of type LocaleContextInfo, which represents a compilation of preferred locales from different sources - user’s profile, portal default, browser language settings, current session, browser cookie … All these different sources of Locale configuration or preference are used as input to LocalePolicy implementation that decides which Locale should be used.

By default, org.exoplatform.portal.application.localization.DefaultLocalePolicyService - an implementation of LocalePolicy - is installed to provide the default behaviour. This, however, can easily be extended and overriden. A completely new implementation can also be written from scratch.

DefaultLocalePolicyService treats logged-in users slightly differently than anonymous users. Logged-in users have a profile that can contain language preference, while anonymous users don't.

Here is an algorithm used for anonymous users.

If no supported locale is found the return locale eventually defaults to portalLocale.

The algorithm for logged-in users is virtually the same except that the first Locale source checked is user's profile.

The easiest way to customize the LocalePolicy is to extend DefaultLocalePolicyService. The study of its source code will be required. There is ample JavaDoc that provides thorough information. Most customizations will involve simply overriding one or more of its protected methods.

An example of a customization is an already provided NoBrowserLocalePolicyService. By overriding just one method, it skips any use of browser language preference.

public class NoBrowserLocalePolicyService extends DefaultLocalePolicyService
{
   /**
    * Override super method with no-op.
    *
    * @param context locale context info available to implementations in order to determine appropriate Locale
    * @return null
    */
   @Override
   protected Locale getLocaleConfigFromBrowser(LocaleContextInfo context)
   {
      return null;
   }
}
         

The LocalePolicy framework is enabled for portlets by configuring LocalizationLifecycle class in portal's webui configuration file: gatein.ear/02portal.war/WEB-INF/webui-configuration.xml:

    <application-lifecycle-listeners>

      ...

      <listener>org.exoplatform.portal.application.localization.LocalizationLifecycle</listener>

    </application-lifecycle-listeners>

         

The default LocalePolicy implementation is installed as GateIn Kernel portal service via gatein.ear/lib/exo.portal.webui.portal-VERSION.jar/conf/portal/configuration.xml.

The following fragment is responsible for installing the service:

    <component>

       <key>org.exoplatform.services.resources.LocalePolicy</key>

       <type>org.exoplatform.portal.application.localization.DefaultLocalePolicyService</type>

   </component>

         

Besides implementing LocalePolicy, the service class also needs to implement org.picocontainer.Startable interface in order to get installed.

This configuration file should not be changed. The configuration in it can be overriden by placing it into portal's .war file: gatein.ear/02portal.war/WEB-INF/conf/configuration.xml (usually as another file included into this one).

In portals all the resources that are not portlets themselves but are accessed through portlets - reading data through PortletRequest, and writing to PortletResponse - are referred to as 'bridged'. Any resources that are accessed directly, bypassing portal filters and servlets, are referred to as 'non-bridged'.

Non-bridged servlets, and .jsps have no access to PortalRequest. They don't use PortletRequest.getLocale() to determine current Locale. Instead, they use ServletRequest.getLocale() which is subject to precise semantics defined by Servlet specification - it reflects browser's language preference.

In other words, non-bridged resources don't have a notion of current Locale in the same sense that portlets do. The result is that when mixing portlets and non-bridged resources there may be a localization mismatch - an inconsistency in the language used by different resources composing your portal page.

This problem is addressed by LocalizationFilter. This is a filter that changes the behaviour of ServletRequest.getLocale() method so that it behaves the same way as PortletRequest.getLocale(). That way even localization of servlets, and .jsps accessed in a non-bridged manner can stay in sync with portlet localization.

LocalizationFilter is installed through portal's web.xml file: gatein.ear/02portal.war/WEB-INF/web.xml

   <filter>

        <filter-name>LocalizationFilter</filter-name>

        <filter-class>org.exoplatform.portal.application.localization.LocalizationFilter</filter-class>

    </filter>



    ...



    <filter-mapping>

       <filter-name>LocalizationFilter</filter-name>

       <url-pattern>*.jsp</url-pattern>

       <dispatcher>INCLUDE</dispatcher>

       <dispatcher>FORWARD</dispatcher>

       <dispatcher>REQUEST</dispatcher>

       <dispatcher>ERROR</dispatcher>

   </filter-mapping>

         

There is a tiny limitation with this mechanism in that it is unable to determine the current portal, and consequently its default language. As a result the portalLocale defaults to English, but can be configured to something else by using filter's PortalLocale init param. For example:

   <filter>

        <filter-name>LocalizationFilter</filter-name>

        <filter-class>org.exoplatform.portal.application.localization.LocalizationFilter</filter-class>

        <init-param>

           <param-name>PortalLocale</param-name>

           <param-value>fr_FR</param-value>

        </init-param>

    </filter> 

         

By default, LocalizationFilter is applied to *.jsp, which is considered the minimum required by GateIn 3.2 to properly keep its non-bridged resources in sync with the rest of the portal. Additionally deployed portlets, and portal applications, may need broader mapping to cover their non-bridged resources.

Avoid using /*, /public/*, /private/*, and similar broad mappings as LocalizationFilter sometimes adversely interacts with the processing of portlet requests. Use multiple filter-mappings instead to specifically target non-bridged resources.

Keeping the mapping limited to only non-bridged resources will minimize any impact on performance as well.

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.

Example 1

In the example we need to use the orientation to modify the float attribute that will make the horizontal tabs either float on left or on right:

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

The LT produced output will be:

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

The RT produced output will be:

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

Example 2

In this example we need to modify the padding according to the orientation:

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

The LT produced output will be:

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

The RT produced output will be:

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

Sometimes it is necessary to create an 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. Usually 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>

In order 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; An application subscribed to "/eXo/application" will receive messages sent on the "/eXo/application/map" topic. A message sent on "/eXo", however, 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 at 0 the upload size is unlimited.

The loading mask layer is deployed after an ajax-call. Its purpose is to block the GUI in order 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 previous instructions have been carried out.

The GUI will be blocked to ensure a user can only request one action at a time and while the request seems to be synchronous, all ajax requests are, in fact 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, in order to work with browsers that do not support Synchronous requests, bAsync is set to always be true (Ajax request will always be asynchronous).

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

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 toward portlet developers. It is also recommend that developers read and understand the JSR-286 Portlet Specification .

|-- SimplestHelloWorld-0.0.1.war
|   `-- WEB-INF
|       |-- classes
|       |   `-- org
|       |       `-- gatein
|       |           `-- portal
|       |               `-- examples
|       |                   `-- portlets
|       |                       `-- SimplestHelloWorldPortlet.class
|       |-- portlet.xml
|       `-- web.xml

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();

   }

}