<document>
<header>
<product>resin</product>
<title>Render Parameters Tutorial</title>
<type>tutorial</type>
<tutorial-startpage>hello</tutorial-startpage>
<description>
<p>
Render parameters are used to maintain state.
</p>
<p>
This tutorial adds the concept of "identity" and "color" to the basic Hello
World example, the identity and color are maintained as render parameters.
</description>
</header>

<body>
<summary/>

<section title="Files in this tutorial">
<deftable>
<tr><td><viewfile-link file="WEB-INF/classes/example/HelloWorldPortlet.java"/>
    <td>Portlet
<tr><td><viewfile-link file="WEB-INF/web.xml"/>
    <td>web-app configuration
</deftable>
</section>

<section title="Portlets are stateless">
<p>
Just like Servlets a Portlet does not maintain state within the Portlet
object.  Many requests, from many different users, may be using an instance of
a portlet at the same time.
</p>

<p>
In this tutorial, the "identity" and "color" are two values to 
contain the state of the portlet.  The portlet provides links to change the
color or identity, and maintains the identity and color from request to
request.
</p>

</section>

<section title="Getting the value of a render parameter">
<p>
The value of a render parameter is obtained from the 
<a href="javadoc|javax.portlet.RenderResponse|getParameter">request</a> 
object using <code>request.getParameter(name)</code>.
</p>

<example title="Getting the value of a render parameter"
         file="WEB-INF/classes/example/HelloWorldPortlet.java">

  public void render(RenderRequest request, RenderResponse response)
    throws PortletException, IOException
  {
    <b>
    String identity = request.getParameter("identity");
    if (identity == null)
      identity = "World";

    String color = request.getParameter("color");
    if (color == null)
      color = "silver";
    </b>

    ...

    out.println("Hello, " + identity + ".");
    out.println("Your favorite color is " + color);

    ...
</example>

</section>

<section title="Setting the value of a render parameter - createRenderURL()">
<p>
The value of a render parameter can be changed on a subsequent request with the
use of 
<a href="javadoc|javax.portlet.RenderRespone|createRenderURL">response.createRenderURL()</a>.  
<code>response.createRenderURL()</code> returns a 
<a href="javadoc|javax.portlet.PortletURL|">PortletURL</a>. 
The <code>PortletURL</code> is used to set render parameters for the 
next request, the <code>toString()</code> method is used to generate
the appropriate url.
</p>

<example title="response.createRenderURL()"
         file="WEB-INF/classes/example/HelloWorldPortlet.java">


    ...


    String identity = request.getParameter("identity");
    String color = request.getParameter("color");

    ...

    // url links to change the name

    PortletURL harryUrl = response.createRenderURL();
    harryUrl.setParameter("identity", "Harry");
    harryUrl.setParameter("color", color);

    PortletURL ronUrl = response.createRenderURL();
    ronUrl.setParameter("identity", "Ron");
    ronUrl.setParameter("color", color);

    ...

    out.println("&lt;li&gt;&lt;a href='" + harryUrl.toString() + "'&gt;Harry&lt;/a&gt;");
    out.println("&lt;li&gt;&lt;a href='" + ronUrl.toString() + "'&gt;Ron&lt;/a&gt;");

    ...


</example>

</section>

</document>
