Creating Struts portlets and projects

Struts portlet projects share common characteristics with standard portlet and Struts projects, although there are some differences that you should be aware of. The Struts portlet project structure and related resources are dictated by the Struts Portlet Framework (SPF) support provided by WebSphere® Portal and included in the Rational® Software Development Platform.

Struts portlet projects are created using either the New Portlet Project or New Portlet Project (JSR 168) wizard. A default Struts-type portlet, and, optionally, a Web diagram file, will be added in the process of creating the project. The wizard automatically generates Struts portlet configuration files and the necessary updates to the web.xml file, portal.xml file, and adds all of the SPF tag libraries and JAR files to the project, in the directory structure that is required.

The following types of resources defined by the Struts Portlet Framework will be included in the project:
Resource type Files Target directory Notes
TLDs
IBM® API portlet
All of the *.tld files in the SPFLegacyBlank.war.
JSR 168 API portlet
All of the *.tld files in the SPFStandardBlank.war.
WEB-INF  
JARs
IBM API portlet
All the *.jar files with the exception of Blank.jar in the SPFLegacyBlank.war.
JSR 168 API portlet
All the *.jar files with the exception of Blank.jar in the SPFStandard.war.
WEB-INF/lib  
Configuration files
  • struts-config.xml
  • struts-config-mode.xml (for different modes/markup)
WEB-INF

The <controller> element that defines the Request Processor class is automatically generated in the Struts configuration file.

Deployment descriptors
  • portlet.xml
  • web.xml
WEB-INF

IBM API portlet

The following modifications are made to the standard web.xml file:

  • The servlet com.ibm.wps.portlets.struts.WpsStrutsPortlet is added.
  • Web-app, servlet, and servlet-mapping tags have ID attributes with string values, suffixed with a unique ID to prevent conflicts with other portlets.
  • WpsStrutsPortlet is configured using a prefix-based mapping, with an extension-based servlet-mapping defined in the struts-servlet-mapping init parameter of the servlet. An extension-based mapping should be used when including Struts links. If you want to run this Struts portlet project as an standalone application, change the servlet-mapping entry from an extension-based servlet-mapping (*.do) to a prefix-based mapping (for example, a URL pattern such as /app/*).
    Note: You cannot use the same configuration for a Web project and a portlet application.
  • Extension-based mapping is required and is defined in the initial parameter for the WpsStrutsPortlet, for the parameter struts-servlet-mapping.
  • Struts portlet tag library definitions are used.
  • Portlet mode configuration information is included in portlet.xml. Since (for SPF) mode and markup are treated as Struts modules, these modules are also defined as part of the initial parameter for the WpsStrutsPortlet.
  • Welcome-file list support for Struts modes is supplied.
  • Struts portlet-related init-param values are supplied.
     

JSR 168 (standard) API portlet

The following items are included in the portlet.xml file:

  • The portlet com.ibm.portal.struts.portlet.StrutsPortlet is added. Note that this is not a servlet entry; it is defined solely in portlet.xml
  • Portlets are uniquely identified with a tag contained within the definition to prevent conflicts with other portlets.
  • Extension-based mapping (such as *.do) is required, and is defined in the initial parameter for the StrutsPortlet, struts-servlet-mapping.
  • Portlet mode configuration information is included in portlet.xml. Since (for SPF) mode and markup are treated as Struts modules, these modules are also defined as part of the initial parameter for the StrutsPortlet.
  • Struts portlet-related init-param values are supplied.
  • The initial page for the supported struts modes are defined in portlet.xml as part of the portlet preferences for this portlet. For example:
    <portlet-preferences>
      <preference>
        <name>com.ibm.struts.portal.page.view.html</name>     <value>index.jsp</value>
      </preference>
      <preference>
        <name>com.ibm.struts.portal.page.edit.html</name>     <value>html/edit/index.jsp</value>
      </preference>
    </portlet-preferences>

Struts portlet tag library definitions appropriate for JSR 168 SPF and the list of Welcome-files supported for Struts modes are included in the web.xml file.

IBM API portlet conventions

The following sample configuration and deployment descriptor file snippets show representative tagging used within Struts portlet projects:

struts-config.xml
The following controller section is added to all struts configuration files:
<controller processorClass="com.ibm.wps.portlets.struts.WpsRequestProcessor">
</controller>
web.xml
This shows a sample Struts portlet servlet added to web.xml. (Struts portlet-specific values in bold.):
<servlet id="Struts_Unique_Servlet_Name">
     <servlet-name>Struts</servlet-name>
     <display-name>Struts Portlet</display-name>
     <servlet-class>com.ibm.wps.portlets.struts.WpsStrutsPortlet</servlet-class>

   <!-- Struts configuration -->
     <init-param>
       <param-name>config</param-name>
       <param-value>/WEB-INF/struts-config.xml</param-value>
     </init-param>
     <init-param>
       <param-name>struts-servlet-mapping</param-name>
       <param-value>*.do</param-value>
     </init-param> 
	 <!-- end of Struts configuration -->
</servlet>
Note: The config parameter above is the standard way to define a Struts configuration file and modules. The struts-servlet-mapping parameter is the way for a Struts portlet to define what to use as a Struts action mapping, so that paths that should be treated as Struts actions can be recognized. This is used the same way as the "servlet-mapping" value when configuring an Apache Struts servlet. It is strongly recommended that extension mapping be used for the param-value.
The following is an example of servlet-mapping for a Struts portlet servlet. It is defined to refer to the Struts portlet, since this portlet is also a servlet.
<servlet-mapping id="Struts_Unique_ServletMapping">
      <servlet-name>Struts</servlet-name>
      <url-pattern>/Struts/*</url-pattern>
</servlet-mapping>
This is an example of additional tag libraries that can be added to web.xml:
<taglib>
    <taglib-uri>/WEB-INF/struts-html.tld</taglib-uri>
    <taglib-location>/WEB-INF/struts-html.tld</taglib-location>
</taglib>
portlet.xml
This is an example of an abstract portlet defined in portlet.xml:
<portlet-app uid="A_Unique_ID:1" major-version="1" minor-version="0">
	<portlet-app-name>Struts Portlet Application</portlet-app-name>
	<portlet id="Portlet_1" 
href="WEB-INF/web.xml#Struts_Unique_Servlet_Name"
major-version="1" minor-version="0">
		<portlet-name>Struts Portlet</portlet-name>
		<cache>
			<expires>0</expires>
			<shared>NO</shared>
		</cache>
		<allows>
			<maximized/>
			<minimized/>
		</allows>
            <supports>
               <markup name="html">
                  <view/>
               </markup>
            </supports>
	</portlet>
</portlet-app>
This is an example of a concrete portlet defined in portlet.xml:
<concrete-portlet-app uid="A_Unique_ID:1.1">
	<portlet-app-name>Struts Blank Application</portlet-app-name>
	<concrete-portlet href="#Portlet_1">
		<portlet-name>Struts Portlet</portlet-name>
		<default-locale>en</default-locale>
		<language locale="en">
			<title>Struts Portlet</title>
			<title-short>Struts Portlet</title-short>
			<description>Struts Portlet</description>
			<keywords>WPS, Struts</keywords>
		</language>
        <config-param>
           <param-name>FilterChain</param-name>
           <param-value>StrutsTranscoding</param-value>
        </config-param>
        <!-- any additional Struts related config-param values added here -->
	</concrete-portlet>
</concrete-portlet-app>
Note: The FilterChain <config-param> parameter is not available in WebSphere Portal v5.1.

JSR 168 (standard) API portlet conventions

The following sample configuration and deployment descriptor file snippets show representative tagging used within Struts portlet projects:

struts-config.xml
The following controller section is added to all Struts configuration files:
<controller processorClass="com.ibm.portal.struts.portlet.WpRequestProcessor">
</controller>
web.xml
This is an example of additional tag libraries to be added to web.xml:
<taglib>
    <taglib-uri>/WEB-INF/struts-html.tld</taglib-uri>
    <taglib-location>/WEB-INF/struts-html.tld</taglib-location>
</taglib>
portlet.xml
This shows a sample Struts portlet added to portlet.xml:.
<portlet>
     <portlet-name>StrutsPortletProject</portlet-name>
     <display-name>StrutsPortletProject portlet</display-name>
		<portlet-class>
			  com.ibm.portal.struts.portlet.StrutsPortlet
    </portlet-class>

   <!-- Struts configuration -->
     <init-param>
       <param-name>config</param-name>
       <param-value>/WEB-INF/struts-config.xml</param-value>
     </init-param>
     <init-param>
       <param-name>struts-servlet-mapping</param-name>
       <param-value>*.do</param-value>
     </init-param> 
	 <!-- end of Struts configuration -->

     <!-- Here is an example of edit mode initialization: -->
     <init-param>
       <param-name>config/html/edit</param-name>
       <param-value>/WEB-INF/struts-html-edit.xml</param-value>
     </init-param>

     <!-- The following snippets are generated by the portlet API. -->
     <expiration-cache>0</expiration-cache>
     <supports>
       <mime-type>text/html</mime-type>
       <portlet-mode>view</portlet-mode>
       <portlet-mode>edit</portlet-mode>
     </supports>
     <supported-locale>en</supported-locale>
     <resource-bundle> strutsportletjsr168.nl.StrutsPorltetJSR168PortletResource	</resource-bundle>
       <portlet-info>
           <title>StrutsPortletJSR168 portlet</title>
       </portlet-info>

   <portlet-preferences> 

   <!-- example of setting the first page of the html view mode --> 
     <preference> 
       <name>com.ibm.struts.portal.page.view.html</name> 
       <value>index.jsp</value> 
     </preference> 

   <!-- example of setting the first page of the html edit mode -->
     <preference> 
       <name>com.ibm.struts.portal.page.edit.html</name>
       <value>html/edit/index.jsp</value>
     </preference>

   </portlet-preferences>

</portlet>
Note: The config parameter above is the standard way to define a Struts configuration file and modules.
Related concepts
Struts portlet applications
Struts Portlet Framework
Working with portlet deployment descriptors
Creating data access Web applications using Struts
Struts tools for application development
Related tasks
Creating Struts portlets
Creating Struts portlet JSP files
Creating Struts applications
Related reference
Differences between Struts 1.1 and SPF tag library classes
Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.