[prev in list] [next in list] [prev in thread] [next in thread]
List: jetspeed-dev
Subject: cvs commit: jakarta-jetspeed/xdocs forwards.xml
From: taylor () apache ! org
Date: 2003-04-25 21:09:00
[Download RAW message or body]
taylor 2003/04/25 14:09:00
Added: xdocs forwards.xml
Log:
- Added Portltets forward docs
- Added parameter docs for db browser
Revision Changes Path
1.1 jakarta-jetspeed/xdocs/forwards.xml
Index: forwards.xml
===================================================================
<?xml version="1.0"?>
<document>
<properties>
<title>Forwards and Links</title>
<subtitle>An introduction to Jetspeed Forwards and Links</subtitle>
<authors>
<person name="David Taylor" email="taylor@apache.org"/>
</authors>
</properties>
<body>
<!---
- Provide examples of user and registry PSML
-->
<section name="Forwards">
<p>
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.
</p>
<subsection name="Configuration: the forwards directory">
<p>
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: \
<b>services.ForwardService.directory=/WEB-INF/conf/forwards/</b> </p>
<p>
All definitions from multiple forward files are merged together. Duplicate \
names are overwritten. There is currently no namespacing in the Forward Service.
</p>
</subsection>
</section>
<section name="Declaring Forwards">
<subsection name="Forward Entries">
<p>
A Forward is defined as an XML entry with one or more of the optional \
formats below: </p>
<source test=""><![CDATA[
<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>
]]></source>
<p>
The three examples below show the three variations of the forward definition:
</p>
<ul>
<li><b>page</b> - A PSML page resource</li>
<li><b>pane</b> - A Pane on the specified page. If a page isn't specified, the \
current page is assumed.</li>
<li><b>portlet</b> - The id of a portlet on the specified page and/or pane. If \
not specified, assumed the current page.</li> </ul>
At least one element must be specified. It is possible to combine all three \
elements (page,pane,portlet), see below. <p>
The first example above defines a <b>Page Forward</b> with the logical name of \
'ApacheGroupNews'. The name attribute is required.
The <b>page</b> element defines which PSML page the forward references. In this \
case, we
reference a Group PSML resource. The page name is <b>news</b>, and the group \
name is <b>apache</b> There are three attributes supported on the page element.
These elements reference a type of Jetspeed Security resource:
</p>
<ul>
<li><b>group</b> - specified the name of a Jetspeed Group.</li>
<li><b>role</b> - specified the name of a Jetspeed Role.</li>
<li><b>user</b> - specified the name of a Jetspeed User.</li>
</ul>
<p>
The second example defines a <b>Pane Forward</b> with the logical name \
'SpecificPane'. In this case, we
reference a PSML Pane resource. The pane name is <b>sports</b>. This pane is on \
the current page. </p>
<p>
The third example defines a <b>Portlet Forward</b> with the logical name \
'PortletMax'. In this case, we
reference a portlet. The portlet ID is <b>myPortlet</b>. 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:
<ul>
<li><b>controls.Maximize</b> - go to maximize mode for the specified \
portlet.</li>
<li><b>controls.Minimize</b> - go to minimize mode for the specified \
portlet.</li>
<li><b>controls.Customize</b> - go to customize mode for the specified \
portlet</li>
<li><b>controls.Info</b> - go to information mode for the specified \
portlet.</li>
<li><b>controls.Print</b> - go to print mode for the specified \
portlet.</li>
<li><b>controls.Close</b> - go to close mode for the specified \
portlet.</li>
<li><b>controls.Restore</b> - go to restore the specified portlet.</li>
</ul>
</p>
</subsection>
<subsection name="Combining Forward Entries">
<p>
The three element types (page, pane, portlet) can be combined:
</p>
<source test=""><![CDATA[
<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>
]]></source>
<p>
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'.
</p>
<p>
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'. </p>
<p>
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'.
</p>
</subsection>
<subsection name="Portlet Forwards">
<p>
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.
</p>
<source test=""><![CDATA[
<portlet-forward portlet='EmployeeForm' forward='EmployeeList' \
target='Success'/>
<portlet-forward portlet='EmployeeForm' forward='DisplayValidation' \
target='Error'/>
<portlet-forward portlet='EmployeeForm' forward='EmployeeAction' \
target='Action'/> ]]></source>
<p>
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. </p>
</subsection>
<subsection name="Forward Query Parameters">
<p>
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.
</p>
<source test=""><![CDATA[
<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>
]]></source>
</subsection>
<subsection name="Forwards and Velocity">
<p>
Here are examples of using forwards from Velocity.
Since a forward returns a DynamicURI, you can add query parameters to it.
</p>
<source test=""><![CDATA[
<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)">
]]></source>
</subsection>
<subsection name="Forwards and JSP">
<p>
Here are examples of using forwards from a JSP.
</p>
<source test=""><![CDATA[
<%@ 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>
]]></source>
</subsection>
<subsection name="Forwards and Java">
<p>
Here are examples of using forwards from Java.
</p>
<source test=""><![CDATA[
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);
]]></source>
</subsection>
</section>
</body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: jetspeed-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: jetspeed-dev-help@jakarta.apache.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic