Creating Portlet URLs on JBoss AS

This knol describes RenderURLs, ActionURLs, how they compare to one another, and their uses all in the context of the JBoss AS.

Prerequisites



Detailed Description

PortletURLs are the links that allow users to navigate and perform actions in a portlet. RenderURLs and ActionURLs are subsets of PortletURLs. They both control where and what the user does, however, each one causes the application to flow differently.



Render URLs

Render URL invokes the doView() function, or more accurately the render phase of a request. This step is meant for generating mark up, and mark up only. No actions should be handled in this portion. This style of url is used for navigation purposes only. The render URL is generated via the response object. To create a render URL, use something similar to the following code:

PortletURL renderUrlObj = response.createRenderURL();
renderUrlObj.setParameter( "name", "value" );
String renderUrlString = renderUrlObj.toString();

Any number of parameters may be set in the URL. The key thing to notice is that the member function 'createRenderURL()' is invoked. The urlString contains the address that is to be used in an anchor, for example:

StringBuilder sb = new StringBuilder();

sb.append( "<a href='" );
sb.append( renderUrlString );
sb.append( "'>Click Me</a>" );

PrintWriter out = response.getWriter();
out.write( sb.toString() );

This would generate something similar to the following html:

<a href='/portal/auth/portal/MyPortal/default/HelloWorldPortletWindow?windowstate=normal&name=value'>Click Me</a>

There is a whole mess of stuff in that url, which is why we let the portlet handle its generation. I will give an explanation of what is seen here. A few of the parts should be obvious, such as MyPortal, which represents the portal name. The part "/portal/auth/portal" signifies two things: That we are using portals and the user is authenticated. It could also have been "/portal/portal", meaning a user hasn't logged in yet. If some other platform was being used, the "/portal/portal" is not necessary. Such is the case when using Servlets in JBoss. The section, "/default", specifies what page/tab the target portlet is in and will direct the user there. The "/HelloWorldPortletWindow" is the target portlet that is to be rendered by the link. Finally, we have the parameters. But there are two name/value pairs? Didn't I only set one? We can see the the name/value pair that we set on the end of the url. The "windowstate=normal" parameter is a parameter telling JBoss the state the window should be in. In this case it should appear as it "normally" should. The windowstate may be change via a function, setWindowState( arg0 ), that is apart of the PortletURL object.




Action URLs

Action URLs are different from Render URLs in that they invoke an extra phase, called the action phase. When action request is sent to the server, the action phase is processed and then the render phase processed. The function, processAction( ActionRequest request, ActionResponse response ) maps to the action phase. An html form will always require an Action URL. However, an Action URL may also be used with a simple anchor.

Here are two example uses of action URLs:

PortletURL createUrlObj = response.createActionURL();
createUrlObj.setParameter( "myAction", "create" );
String createUrlString = createUrlObj.toString();

PortletURL deleteUrlObj = response.createActionURL();
deleteUrlObj.setParameter( "myAction", "delete" );
deleteUrlObj.setParameter( "id", "1234" );
String deleteUrlString = deleteUrlObj.toString();

In these cases, I will use the createUrlString in a form and the deleteUrlString as a normal link:

StringBuilder create = new StringBuilder();
create.append( "<form action='" );
create.append( createUrlString );
create.append( "' method='post'>" );
create.append( "ID: <input type='text' name='id' /><br />" );
create.append( "Description: <input type='text' name='description' /><br />" );
create.append( "<input type='submit' value='Submit' />" );
create.append( "</form>" );

StringBuilder delete = new StringBuilder();
delete.append( "<a href='" );
delete.append( deleteUrlString );
delete.append( "'>Delete Item 1234</a>" );

StringBuilder pageContent = new StringBuilder();
pageContent.append( create );
pageContent.append( "<br />" );
pageContent.append( delete );

PrintWriter out = response.getWriter();
out.write( pageContent.toString() );

This will produce html similar to the following:

<form action='/portal/auth/portal/MyPortal/default/HelloWorldPortletWindow?action=1&myAction=create' method='post'>
ID: <input type='text' name='id' /><br />
Description: <input type='text' name='description' /><br />
<input type='submit' value='Submit' />
</form>
<br />
<a href='/portal/auth/portal/MyPortal/default/HelloWorldPortletWindow?action=1&myAction=delete&id=1234'>Delete Item 1234</a>

For the most part, these urls that were generated are exactly the same as the render url. Notice the extra name/value pair that was generated, the 'action=1'. This is the only thing that differentiates an action url from a render url in the html. It is strongly advised not to add this parameter in a render url. Both of these ursl will invoke the processAction() method on a portlet. The form will have a few more parameters when the request gets to the server because of the input fields.




Do View

Do view is meant for deciding what markup needs to be displayed and generating it. While you can perform actions here, it is highly recommended that you don't. The doView() method takes two parameters: a RenderRequest and a RenderResponse. The request object contains either the request/results of the processAction() method or the request from the user. The response is then used to send the information to the user. The only database actions that typically occur here is data retrieval for displaying purposes.



Process Action

The process action method is meant to perform any transactions that the user has requested and direct the user to the doView method. The parameters that the processAction() method require are an ActionRequest and an ActionResponse. These are similar to the RenderRequest and RenderResponse that doView() requires. The request object provides the parameters and the response forwards the results to the doView method. Note that the parameters found in the ActionRequest will not be forwarded to the RenderRequest unless they are explicitly transferred. See the diagram at the bottom to get a better idea of the control flow.

To foward information from processAction() to doView() you'll need to use the following:

processAction( ActionRequest request, ActionResponse response ) {

    String value = request.getParameterValue( "someName" );
    response.setRenderParameter( "someName", value );
}



Portlet Life Cycle

Comments

Matt
Matt
Web Developer at Burris Logistics
Milton, DE
Article rating:
Your rating:

Categories

Based on community consensus.

Activity for this knol

This week:

25pageviews

Totals:

1143pageviews
©2009 Google