Generic MVC Portlet


Class Name : org.apache.jetspeed.portal.portlets.GenericMVCPortlet


Description

Present content rendered via a the MVC pattern using a templating language(Velocity of JSP) in a portlet.

Element: parameter

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 NameDescription
viewtypeThe 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.

Example of Registry Entry

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

Explanation of the Generic MVC Portlet's action/render phase

It is important to understand the Generic MVC Portlet's render and action phasing to properly understand what is going on.

History

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.

Generic MVC Portlet anction/render phase

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.

Development Guidelines

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.

Example of Portlets

Jetspeed include the following example of Velocity porlets.

Portlet NameDescription
HelloVelocityBasic Velocity portlet
JSLINK Example Display the uses of $jslink