Quick start guide

Getting Started with Tapestry5 Portlet

If you want to see it in action with Apache Pluto, you just need to:
- Download the sources
- Go to the repository directory
- Run "mvn jetty:run"
- Open your browser to http://localhost:8080/tapestry5-portlet/portal/Index

If you are a gradle user you can try:
- gradle jettyRun

Create your first portlet

Maven Dependencies

First of all, you will need to add those dependencies in your pom.xml. Of course your pom.xml file will also contain the common dependencies needed to develop web application with Tapestry (tapestry-core, tapestry-ioc, servlet-api)

		<dependency>
  			<groupId>org.apache.tapestry.portlet</groupId>
  			<artifactId>tapestry5-portlet</artifactId>
  			<version>5.3.2</version> //for Tapestry 5.3.x 
		</dependency>
		<dependency>
  			<groupId>javax.portlet</groupId>
  			<artifactId>portlet-api</artifactId>
  			<version>2.0</version>
  			<type>jar</type>
  			<scope>provided</scope>
		</dependency>

The "tapestry5-portlet" is a contribution to Tapestry default implementation that adds portlet support to your Tapestry developments. The "portlet-api" dependency is required to allow you to manipulate portlet API features like PortletRequest or PortletPreferences inside your Tapestry pages.

Important Note : the provided scope for "portlet-api" dependency is important to avoid conflicts while deploying your application in a portlet container.

Deployment Descriptors

This file is the standard descriptor recognized by all the portlet specifications implementors. It contains the descriptions of all the existing portlets packaged inside your application. Let's start with a brief example:

		<?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" version="2.0"
       			 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>
   		...
    		<portlet>
      		      <portlet-name>TapestryPortlet</portlet-name>
      		      <portlet-class>org.apache.tapestry5.portlet.ApplicationPortlet</portlet-class>
      		      <supports>
        		<mime-type>text/html</mime-type>
        	         <portlet-mode>VIEW</portlet-mode>
      		      </supports>
		      <supports>
		        <mime-type>image/png</mime-type>
		        <portlet-mode>VIEW</portlet-mode>
		      </supports>
		      <portlet-info>
		        <title>Tapestry Portlet</title>
		        <short-title>Tapestry Portlet</short-title>
		        <keywords> Tapestry  Portlet</keywords>
		      </portlet-info>
		      <portlet-preferences>
		        <preference>
		          <name>MyPreference</name>
		        </preference>
		      </portlet-preferences>
		      <security-role-ref>
		        <role-name>user</role-name>
		      </security-role-ref>
		      <supported-public-render-parameter>publicParam</supported-public-render-parameter>
		      <container-runtime-option>
		        <name>javax.portlet.renderHeaders</name>
		        <value>true</value>
		      </container-runtime-option>
		 </portlet>
		    ...
		 <default-namespace>http://localhost:8080</default-namespace>
		    <public-render-parameter>
		      <identifier>publicParam</identifier>
		      <name>publicParam</name>
		     </public-render-parameter>     
		</portlet-app>

Let's describe this snippet in details:

First of all, we have the "portlet-app" element that is the root element of portlet.xml descriptor.

Then we have a "portlet" element for each portlet definition, inside this element we will describe all the features related to the current portlet definition.

The "portlet-name" is the name of the portlet as it will appear in the portal administration GUI. This name must match an existing Tapestry page in your application. Without a matching page, the page resolution will fail.

The "portlet-class" is the class of your portlet. In case of Tapestry this will always be the same class unless you need to implement specific behaviour in init() and destroy() methods. The implementation we provide is generic and acts as a dispatcher on your Tapestry application

The "supports" element describes the supported mime types and their corresponding mode. As a reminder, three modes exist in Portlet specifications: VIEW, EDIT and HELP.

Then, we have general information about the current Portlet

Afterwards, you will define the list of preferences associated to your Portlet and define their default values

The "supported-public-render-parameter" is important because it describes which render parameter must be passed to the portlet instance. Important : This must refer to an existing "public-render-parameter"

Finally, you have to declare at least one runtime option. Without javax.portlet.renderHeaders set to true, the Tapestry portlet contribution will not be able to properly include JS and CSS files in the containing portal page.

Web.xml

Because a portlet application is also a web application, you have to define the web.xml file. In this file you will declare a regular Tapestry configuration. That will also be useful if you want to run the page you have developed in a standard servlet container.

Important note: Tapestry filter must be declared and fully configured in the "web.xml" file. The generic Tapestry ApplicationPortlet is not in charge of loading Tapestry registry; it will only retrieve it from the portlet context that is shared with servlet context. Follow the snippet below to create your "web.xml" file:

		<?xml version="1.0" encoding="UTF-8"?>
		<!DOCTYPE web-app
		        PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
		        "http://java.sun.com/dtd/web-app_2_3.dtd">
		<web-app>
		  <display-name>Tapestry Demo Application</display-name>
		  <context-param>
		    <param-name>tapestry.app-package</param-name>
		    <param-value>net.atos.tapestry</param-value>
		  </context-param>
		       
		  <context-param>
		    <param-name>tapestry.combine-scripts</param-name>
		    <param-value>false</param-value>
		  </context-param>
		 
		   <filter>
		     <filter-name>TapestryPortlet</filter-name>
		     <filter-class>org.apache.tapestry5.TapestryFilter</filter-class>
		   </filter>
		 
		   <filter-mapping>
		     <filter-name>TapestryPortlet</filter-name>
		     <url-pattern>/*</url-pattern>
		   </filter-mapping>
		</web-app>

The "tapestry.app-package" context parameter that points to the root application package is the place where Tapestry will find pages and components.

Setting the "tapestry.combine-scripts" to false will ease the JS and CSS include in portal page Markup.