Present content rendered via a the MVC pattern using a templating language(Velocity of JSP) in a portlet.
Only the template and viewtype parameters are required. If the "action" parameter is defined, the referenced class may require additional parameters.
Parameters common to many portlets.
| Parameter Name | Description |
|---|---|
| viewtype | The type of View Processor to use. Currently, there are six View Processors to choose from. |
| action |
Name of action class, relative to org.apache.jetspeed.modules.actions.
The class file is expected in <jetspeed_home>WEB-INF/classes/org/apache/jetspeed/modules/actions.
This parameter is optional. |
| template | Name of VM file. The file is expected in <jetspeed_home>WEB-INF/templates/vm/media_type. |
<portlet-entry name="PortalSearch" hidden="false" type="ref" application="false" parent="GenericMVCPortlet">
<meta-info>
<title>Search Portlet</title>
<description>Sample Search Portlet to index and search web sites</description>
</meta-info>
<parameter name="template" value="search" hidden="true"/>
<parameter name="viewtype" value="Velocity" hidden="true"/>
<parameter name="action" value="portlets.SearchAction" hidden="true"/>
<media-type ref="html"/>
<category>search</category>
</portlet-entry>
It is important to understand the Generic MVC Portlet's render and action phasing to properly understand what is going on.
In the past, portlets were required to use Turbine actions. The action parameter on the url was required in order to execute an action on a portlet. When Turbine processed the incoming URL, it would execute the action that was passed in on the URL. This action occurred first, before any rendering had started. Two side effects of the action firing first were: 1) redirects could be used to forward the portal to another PSML and 2) data could be placed into the session or user temp and other porltets would render updated content.
With the Genereic MVC Portlet, actions are fired directly before a portlet's content is rendered. The action is not specified in the URL, but is instead specified in the registry. To fire an action, simply specifying an eventSubmit_domyaction on the url will fire domyaction if that method exists in the action class. However, this also allows multiple portlets domyaction method to fire. To limit this to the actual portlet instance that was used to submit the action, one needs to specify the portlet id on the URL as well.
$jslink.getPortletById($portlet.ID).addQueryData("eventSubmit_domyaction", "1")
Since the action is now being fired during the render process, it is now too late for redirects. This can somewhat complicate development of portlets/psmls that depend on each other. Also, now that the action is not fired until directly before rendering, any dependant portlets may not see any data changes until a second browser refresh.
Here are some guidelines to developing your portlet when using the Generic MVC Portlet.
Use multiple templates when necessary
In your action, calling setTemplate allows you to change the currently displayed template. This can cut down on messy Velocity/JSP code to handle different display states within the same file.
Use PortletSessionState and PortletConfigState
PortletSessionState provides methods for setting/getting/removing data for a specific portlet instance. This allows you to keep session data without worrying about overwriting another portlet's data.
PortletConfigState provides access to helpful methods for retrieving and setting parameters for a portlet.
Avoid Writing Your Own Portlet
With the GenericMVCPortlet, there is usually not a need to write your own class. Simply create a registry entry and use GenericMVCPortlet as the parent. All you need to do is provide a template. If you wish to provide dynamic content, provide an action parameter in the registry and write an action instead.
Always derive from GenericMVCAction
Continuing from the previous tip, if developing dynamic content, simply subclass the GenericMVCAction class. There is no need to subclass either the VelocityPorltetAction of the JspPortletAction. Both of these classes derive from GenericMVCAction themselves. By subclassing directly from GenericMVCAction, you can switch between JSP and Velocity without having to worry about touching you action class.