Using a RequestParamAction

by Andreas Hartmann

Request parameters are used to send data to a server-side program. They can be used in various ways. For instance, they can be

  • forwarded to an external CGI program or servlet,
  • used to create other parameters for external servlets,
  • used to identify the XML source or the XSLT stylesheets used by Cocoon or
  • used to provide input data for XSP pages.

This tutorial shows some uses of request parameters.

What is a RequestParamAction?

Maybe the easiest way to work with request parameters is using a RequestParamAction. A RequestParamAction makes request details available in the sitemap pipeline. By now, these parameters are:

  • {context} - the context path of the Cocoon servlet (usually /cocoon after a new installation)
  • {requestURI} - the requested URI without parameters
  • {requestQuery} - the query string, for example "?param1=value1&param2=value2"

One problem about using RequestParamActions is that there is no way to pass anything to the CGI program with the POST method. But if GET is all you need, these actions provide a flexible way to pass parameters to your CGI program.

Defining the Action

First, you have to include the definition of this action in the components section of your sitemap: 

<map:components>
  ...
  <map:actions default="request">
    <map:action name="request"
      src="org.apache.cocoon.acting.RequestParamAction"/>
  </map:actions>
  ...
</map:components>

Using the Action

In your pipeline, you use the action to pass the query string to your CGI resource. To use the parameters from the query string in the sitemap, you must set the "parameters" parameter of the action to "true". In this example, we define the XSLT stylesheet via a stylesheet parameter in the query string. E. g., if the URI 

page.html?param=test&stylesheet=homepage

is requested, the program 

http://host.com/page.cgi?param=test&stylesheet=homepage

is called and the result is processed through the homepage.xsl stylesheet.

Notice the usage of {../1} within the <map:generate> statement. This is necessary to access a parameter of the parent context (<map:match>). If you just wrote {1}, you wouldn't get the value of the first asterisk in the match pattern, but of the parameter "1" in the request query! 

<map:match pattern="*">
  <map:act type="request">
    <map:parameter name="parameters" value="true"/>
    <map:generate src="http://host.com/{../1}.cgi{requestQuery}"/>
    <map:transform src="{stylesheet}.xsl"/>
  </map:act>
  <map:serialize/>
</map:match>

Of course, you can use a RequestParamAction to pass parameters to a XSL stylesheet: 

<map:match pattern="*">
  <map:act type="request">
    <map:parameter name="parameters" value="true"/>
    <map:generate src="http://host.com/{../1}.cgi{requestQuery}"/>
    <map:transform src="{stylesheet}.xsl">
      <map:parameter name="use-request-parameters" value="true"/>
      <map:parameter name="page-title" value="{page-title}"/>
    </map:transform>
  </map:act>
  <map:serialize/>
</map:match>