Forwards abstract navigation around the portal into centralized XML files, containing logical forward names, and forward parameters. The service decouples your action code from hard-coding portal references. By referencing a forward name as the next page, the navigation from actions and templates are no longer 'hard-coded' in the Java source or template code. Forwards are supported in Java and Velocity as a Forward Tool. JSP will soon be supported.
Forward definitions are stored in XML files. As of version 1.4b4, you must edit this XML file by hand. In order for your changes to take effect, you must restart the application server. The forwards directory is where the user can place forward declarations. The service supports one or more forward declaration files. The location of the forwards directory is configured in the JetspeedResources.properties: services.ForwardService.directory=/WEB-INF/conf/forwards/
All definitions from multiple forward files are merged together. Duplicate names are overwritten. There is currently no namespacing in the Forward Service.
A Forward is defined as an XML entry with one or more of the optional formats below:
<forward name='ApacheGroupNews'>
<page name='news' group='apache'/>
</forward>
<forward name='SpecificPane'>
<pane name='sports'/>
</forward>
<forward name='PortletMax'>
<portlet id='myPortlet' action='controls.Maximize'/>
</forward>
The three examples below show the three variations of the forward definition:
The first example above defines a Page Forward with the logical name of 'ApacheGroupNews'. The name attribute is required. The page element defines which PSML page the forward references. In this case, we reference a Group PSML resource. The page name is news, and the group name is apache There are three attributes supported on the page element. These elements reference a type of Jetspeed Security resource:
The second example defines a Pane Forward with the logical name 'SpecificPane'. In this case, we reference a PSML Pane resource. The pane name is sports. This pane is on the current page.
The third example defines a Portlet Forward with the logical name 'PortletMax'. In this case, we reference a portlet. The portlet ID is myPortlet. This portlet is on the current page. An action is specified with the portlet. You can use any valid Jetspeed action that you are defined, or one of the built-in portlet actions:
The three element types (page, pane, portlet) can be combined:
<forward name='Example1'>
<page name='weather' role='client'/>
<pane id='southwest'/>
</forward>
<forward name='Example2'>
<page name='sports' user='Elvis'/>
<pane id='sports,football'/>
</forward>
<forward name='PortletCustomize'>
<page name='default' group='Jetspeed'/>
<portlet id='myPortlet' action='controls.Customize'/>
</forward>
<!-- Action Forwards -->
<forward name='ServerAction'>
<portlet id='ServerPortlet' action='portlets.cms.ServerFormAction'/>
</forward>
The first example above defines a forward combining a page and pane. We are referencing a page named 'client' for the role 'weather'. On that page, we navigate to a pane named 'southwest'.
The second example defines a forward combining a page and pane. We are referencing a page named 'sports' for the user named 'Elvis'. On that page, we navigate to a sub-pane named 'football' of the pane named 'sports'.
The third example defines a forward combining a page and a portlet. We are referencing the default page for the Jetspeed group. On that page, we navigate to customize a portlet named 'myPortlet'.
A Portlet Forward is defined as an XML entry in a forwards file. Portlet Forwards allow for another level of abstraction, associated a name, usually representing a portlet, and a target, which associates a target or action with the portlet.
<portlet-forward portlet='EmployeeForm' forward='EmployeeList' target='Success'/>
<portlet-forward portlet='EmployeeForm' forward='DisplayValidation' target='Error'/>
<portlet-forward portlet='EmployeeForm' forward='EmployeeAction' target='Action'/>
The examples above shows two portlet forwards for a portlet named 'EmployeeForm'. The first target is named 'Success'. When the program reaches a success state, it should forward to the forward named 'EmployeeList'. The 'Error' target represents a forward to a logical error resource called 'DisplayValidation'. The third example demonstrates a general action invoker for all action events on a given portlet.
Both a forward and a portlet forward definition may include query parameters. Each qparam is added to the generated portal URI as query parameters. Query parameters can be added from via a forward definition, a portlet forward definition, a template (Velocity or JSP), and finally a dynamic forward (from Java). When query parameters have the same name, the portlet forward will override the forward's definition, and the template forwards override all.
<portlet-forward portlet='EmployeeList' forward='EmployeeForm' target='Add'>
<qparam name='ui_mode' value='Add'/>
</portlet-forward>
<portlet-forward portlet='Test' forward='TestForm' target='Validate'>
<qparam name='msg' value='2'/>
<qparam name='ui_mode' value='Validate'/>
</portlet-forward>
Here are examples of using forwards from Velocity. Since a forward returns a DynamicURI, you can add query parameters to it.
<a href="$jsforward.forward('ApacheGroupNews')">Simple Forward</a>
<a href="$jsforward.forward('ForwardDemo','Pane')">Portlet Forward</a>
<a href="$jsforward.forward('WebsiteForm','Edit').addQueryData("ui_rowid",$id)">
Here are examples of using forwards from a JSP.
<%@ taglib uri='/WEB-INF/templates/jsp/tld/template.tld' prefix='jetspeed'%>
<a href="<jetspeed:forward name="AnonymousHome"/>Forward to anonymous home page</a>
<a href="<jetspeed:forward name="ForwardDemo" target="Pane"/>Forward to a Portlet and Target</a>
Here are examples of using forwards from Java.
fs.forward(rundata, getPortletName(), Constants.FWD_SUCCESS);
...
fs.forward(rundata, Constants.FWD_UPDATE_FAILURE);
...
Map map = new HashMap();
map.put("dynamic", "44");
map.put("msgok", "no");
map.put("msg", "3");
ForwardService fs = (ForwardService)ServiceUtil.getServiceByName(ForwardService.SERVICE_NAME);
fs.forwardDynamic(rundata, PORTLET_NAME, "Success", map);