From VYRE

This guide gives a brief overview of how to deploy a third-party portlet application in VYRE Unify. This allows Unify users to add instances of portlets from the applications to pages created with Unify. The current version of VYRE Unify when this guide is written is 4.3.1.

The intended audiences for this guide are developers of portlet applications, and/or system administrators that need to deploy third-party portlet applications in VYRE Unify.

Terminology

A brief definition of some of the terms used in this document:

• Portlet: Portlets are pluggable user interface components that are managed and displayed in a web portal. Portlets produce fragments of markup code that are aggregated into a portal page. The Java Portlet Specification JSR-168 defines a contract between the portlet container and portlets and provides a convenient programming model for portlet developers.
• Portal: A portal is an application which aggregates portlet applications together in a presentable format. It manages the location of a portlet on a page, settings, user preferences and access control for each portlet instance. For the actual invocation of the portlet, the portal uses the underlying portlet container, and then takes the output and aggregates into a page.
• Portlet container: A portlet container sits between a portal and its portlets. A portlet container provides a runtime environment for portlets implemented according to the Portlet API. It controls the life cycle of the portlet and provides it with necessary resources and information about its environment. A portlet container is responsible for initializing and destroying portlets and also for passing user requests to it and collecting responses. The portlet container is not a stand-alone container like the servlet container; instead it is implemented as a thin layer on top of the servlet container and reuses the functionality provided by the servlet container.
• Portlet application: The Java Portlet Specification specifies the packaging and deployment of portlets as part of standard Web Application Archive (WAR) files that may contain other web components, such as JSPs and servlets. This application is called a portlet application. In contrast to servlet-only Web applications, portlet applications consist of two deployment descriptors: one to specify the Web application resources (web.xml) and one to specify all portlets and portlet-related configurations portlet.xml. Also, portlet applications cannot be directly accessed via a browser; they can only be accessed via a portal.
• VYRE Unify: VYRE Unify is flexible framework for the creation and management of dynamic content driven websites and web based applications. Unify has a built-in portal, which uses the EXO portlet container. Any JSR-168 compliant portlet applications can be deployed in Unify.

Preparing a Portlet Application for Unify

Configuring portlet.xml and web.xml

Before you deploy your portlet application in VYRE Unify, you need to make sure that the web application descriptor web.xml file is correctly formatted. This is essential for the Unify to be able to invoke the portlets.

First of all, if you use VYRE API in the portlet application, you need to add the following listener to web.xml:

<web-app ...>
 
  ...
 
  <display-name>${applicationPath}</display-name>
  <description>${applicationDescription}</description>
 
  <listener>
    <listener-class>
      org.exoplatform.services.portletcontainer.impl.servlet.PortletApplicationListener
    </listener-class>
  </listener>
 
  <servlet>
    <servlet-name>PortletWrapper</servlet-name>
    <servlet-class>
      org.exoplatform.services.portletcontainer.impl.servlet.ServletWrapper
    </servlet-class>
  </servlet>
 
  <servlet-mapping>
    <servlet-name>PortletWrapper</servlet-name>
    <url-pattern>/PortletWrapper</url-pattern>
  </servlet-mapping>
 
  ...
 
</web-app>

Now, let’s have a look at how to define portlets for VYRE Unify in web.xml. First we describe a "plain vanilla" portlet, and then we describe a "Spring enabled" portlet. The portlet descriptor (portlet.xml) does not need to be modified. However, we will include snippets from portlet.xml in the description below, mainly to emphasize how VYRE Unify uses the settings there.

Plain vanilla portlet

For a regular "plain vanilla" portlet, the definition in portlet.xml will look something like this:

<portlet-app ...>
 
  ...
 
  <portlet>
    <description>This is my test portlet.</description>
    <portlet-name>MyTestPortlet</portlet-name>
    <display-name>My test portlet</display-name>
    <portlet-class>com.example.MyTestPortlet</portlet-class>
    <expiration-cache>0</expiration-cache>
    <supports>
      <mime-type>text/html</mime-type>
      <portlet-mode>EDIT</portlet-mode>
      <portlet-mode>HELP</portlet-mode>
    </supports>
    <supported-locale>en</supported-locale>
    <portlet-info>
      <title>My test portlet</title>
      <short-title>My test portlet</short-title>
    </portlet-info>
  </portlet>
 
  ...
 
</portlet-app>

There are other settings, but these are the ones that Unify uses.

• Portlet modes: The only thing to mention here is that VYRE Unify assumes that each portlet has a VIEW mode. If this is not true, the portlet will not be displayed correctly in VYRE Unify. Since this is assumed, there is no need to list the VIEW mode in portlet.xml.

Spring portlet

VYRE recommends using the Spring portlet framework for building portlets. Note that the configuration described here is just one of a few configurations that can be used with Spring. For a Spring portlet, the definition in portlet.xml will look something like this:

<portlet-app ...>
 
  ...
 
  <portlet>
    <description>This is my test portlet.</description>
    <portlet-name>MyTestPortlet</portlet-name>
    <display-name>My test portlet</display-name>
    <portlet-class>org.springframework.web.portlet.DispatcherPortlet</portlet-class>
    <init-param>
      <name>contextConfigLocation</name>
      <value>/WEB-INF/context/my-test-portlet.xml</value>
    </init-param>
    <expiration-cache>0</expiration-cache>
    <supports>
     <mime-type>text/html</mime-type>
      <portlet-mode>EDIT</portlet-mode>
      <portlet-mode>HELP</portlet-mode>
    </supports>
    <supported-locale>en</supported-locale>
    <portlet-info>
      <title>My test portlet</title>
      <short-title>My test portlet</short-title>
    </portlet-info>
  </portlet>
 
  ...
 
</portlet-app>

The same applies here for expiration cache and portlet modes. The only difference here from the "plain vanilla" portlet is the following:

• Portlet class: This is the same for all spring enabled portlets:
  • org.springframework.web.portlet.DispatcherPortlet
• Init param: An initialization parameter is provided, pointing to the bean context file for the portlet.

In web.xml, you will need to define a special listener and servlet for Spring:

<web-app ...>
 
  ...
 
  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>/WEB-INF/context/applicationContext.xml</param-value>
  </context-param>
 
...
 
  <listener>
    <listener-class>
      org.springframework.web.context.ContextLoaderListener
    </listener-class>
  </listener>
 
  ...
 
  <servlet>
    <servlet-name>ViewRendererServlet</servlet-name>
    <servlet-class>
      org.springframework.web.servlet.ViewRendererServlet
    </servlet-class>
    <load-on-startup>1</load-on-startup>
  </servlet>
 
  ...
 
  <servlet-mapping>
    <servlet-name>ViewRendererServlet</servlet-name>
    <url-pattern>/WEB-INF/servlet/view</url-pattern>
  </servlet-mapping>
 
  ...
 
</web-app>

The contextConfigLocation parameter points to an application context shared by all portlets. Then the portlet also needs to be defined in portlet.xml:

<portlet-app ...>
 
  ...
 
  <portlet>
 
    ...
 
    </display-name>
    <init-param>
      <param-name>contextConfigLocation</param-name>
      <param-value>/WEB-INF/context/my-test-portlet.xml</param-value>
    </init-param>
    <expiration-cache>
 
    ...
 
  </portlet>
 
  ...
 
</portlet-app>

The only thing different here from the "plain vanilla" portlet is the "init-param" that specifies where the bean context for the portlet is located.

Deploying the Portlet Application

Crosscontext

Since the VYRE Unify portal web applications need to invoke the portlets from a separate web application, you must ensure that these web applications are defined as "cross-context" applications in your application server (or servlet-container). How this is done differs between application servers.

Location of the Portlet Application

The portlet application folder must reside in the same parent folder as the VYRE Unify web applications. The reason for this is how the automatic detection mechanism in the Unify portal works. Also, the context path of the portlet application must be the same as the name of the portlet application folder.

This requirement is being revised at the moment, and future releases of VYRE Unify aim to make the deployment of portlet applications easier and platform independent.

Avoiding JAR conflicts

The JAR files that VYRE Unify is dependent on must be loaded by the class loader that is the parent of the web application class loaders. Therefore, you must make sure that the JARs used by your portlet application (under /WEB-INF/lib) do not conflict with the JARs that come with VYRE Unify.

Ignoring this requirement may cause system crash.

Using the deployed Portlets

After deploying the portlet application, and restarting the VYRE instance, navigate to a page on a site in the publishing part of the VYRE Unify backend. Click on a blue bar on the page and push the "add portlet" button. This will bring up the portlets detected by VYRE Unify. Simply find your portlet, and click it to add it to the page. This will bring you to the EDIT mode of the portlet. Save, and navigate to the VIEW mode to view the page.

You will notice when adding portlets that they are grouped. By default, all ungrouped portlets will go into the "Other" group. There is a file called WEB-INF/portlet_groups.xml under both the vyre4 and www web applications that defines which portlets go into which group. Future versions of VYRE Unify will automatically create a group for each portlet application.