xml-general-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From shan...@apache.org
Subject cvs commit: xml-site/targets/cocoon/developing/webapps/images bottom.gif button-asf-lo.gif button-w3c-lo.gif button-xml-lo.gif close.gif dot.gif join.gif label-background_a.gif label-background_b.gif line.gif logo.gif note.gif right.gif separator.gif void.gif
Date Mon, 15 Jul 2002 14:10:34 GMT
shannon     2002/07/15 07:10:33

  Added:       targets/cocoon/developing/webapps authentication.html
                        index.html portal.html session.html sunrise.html
                        sunshine.html sunspot.html
               targets/cocoon/developing/webapps/images bottom.gif
                        button-asf-lo.gif button-w3c-lo.gif
                        button-xml-lo.gif close.gif dot.gif join.gif
                        label-background_a.gif label-background_b.gif
                        line.gif logo.gif note.gif right.gif separator.gif
                        void.gif
  Log:
  release 2.0.3 update
  
  Revision  Changes    Path
  1.1                  xml-site/targets/cocoon/developing/webapps/authentication.html
  
  Index: authentication.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>Authentication Framework</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">Authentication Framework</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Dev Guide</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Webapps</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Overview</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Authentication</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../howto/xmlform-wizard/howto-xmlform-wizard.html">Form Handling</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="portal.html">Portal</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Scratchpad</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunshine.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunrise.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunspot.html">Portal</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
      
      
    <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Introduction</font>
  <hr style="color: #0086b2" size="1">
      
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i>IMPORTANT: This document conforms to the development version of Cocoon. So
          you will only find these components in the current CVS. An early alpha version is already
          available in the latest release of Cocoon, you will find an introduction <a href="sunrise.html">here</a>.
      </i></font></td>
  </tr>
  </table>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The central point for building a web application is authentication. The Cocoon
          authentication package is a flexible module for authentication and user management. 
          A user can be legitimated using any information available via any source, e.g. a database or
          LDAP. With this mechanism it is very easy and fast to use an exisiting user
          management/authentication system.</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Sitemap-Components</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The authentication Framework adds some actions to the sitemap: the <i>auth-protect</i>
          action, the <i>auth-login</i> action, the <i>auth-logout</i> action
          and the <i>auth-loggedIn</i> action. The <i>authentication-manager</i> gets
          the configuration for the authentication framework and the actions controle the pipelines. 
          The <i>auth-login</i> and the <i>auth-logout</i> action control the
          authentication whereas the <i>auth-loggedIn</i> action controls the application
          flow.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The use of the authentication framework and its components is described in the following
          chapters.</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">User Authentication</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">One feature of the framework is the user authentication. A document can be
          accessible for everyone or it can be protected using this framework. The process of
          requesting a document can be described as follows:</font>
  </p>
       
  <blockquote>
  <ol>
          
  <li>
  <font face="verdana, helvetica, sans serif">The user request a document (original document).
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">The framework checks if this document is protected. If no protection
            is specified, the response to the request is this original document.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">The document is protected and the framework checks, if the user is
            authenticated to view it.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">If the user is authenticated, the response is the original
            document. If not the framework redirects to a special redirect-to document. This
            redirect-to document is freely configurable and can for example contain
            information about the unauthorized access and in addition a login form.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">Using the login form an authentication resource can be called
            with the corresponding user information (e.g. user id and password). This
            authentication resource uses the framework for the authentication process.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">In case of a successful authentication the framework can redirect to
            the original document (or to any configured start document).
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">If the authentication failed another document is invoked by
            the framework displaying information to the user.
          </font>
  </li>
       
  </ol>
  </blockquote>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This process is only one example for a use-case of the framework. It
          can be configured for any authentication scheme. All resources are freely
          configurable.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Authentication handler</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The basic object for authentication is the authentication
            handler. It controlles the access to the resources. Each resource in the
            sitemap can be related to exactly one authentication handler. All resources belonging
            to the same handler are protected in the same way. If a user has access to the
            handler, the user has the same access rights for all resouces of this
            handler.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each authentication handler needs the following mandatory
            configuration:</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">A unique name.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The authentication resource which does the real
               authentication.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The redirect-to document where the framework redirects to for any
               unauthorized request.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using a unique name for each handler (only alphabetical characters
            and digits are allowed for the handler name), the framework manages different
            handlers. So various parts of the sitemap can be protected in different ways. A
            document can be protected by calling this handler using the <i>auth-protect</i>
            action. The "auth-protect" action must be included in the pipeline of the
            resource. It gets the handler information as a parameter:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="protectedresource"&gt;
    &lt;map:act type="auth-protect"&gt;
      &lt;map:parameter name="handler" value="unique handler name"/&gt;
      &lt;map:generate src="source/resource.xml"/&gt;
    &lt;/map:act&gt;
          ...
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the pipeline does not use the "auth-protect" action or the
            parameter "handler" is missing, the document is accessible by any user.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The redirect-to document</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the requested document is not accessible for the user, the framework
            redirects to a special redirect-to document. This document is a mandatory
            configuration of the authentication handler:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;autentication-manager&gt;
    &lt;handlers&gt;
      &lt;!-- Now follows the handlers configuration --&gt;
      &lt;handler name="unique"&gt;
        &lt;redirect-to uri="cocoon://loginpage"/&gt; &lt;!-- The login resource --&gt;
      &lt;/handler&gt;
    &lt;/handlers&gt;
  &lt;/autentication-manager&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This redirect-to document is an unprotected document in the
            sitemap. For tracking which document was requested, the redirect-to document
            gets the request parameter "resource" with the value. In addition all
            parameters specified inside the <i>redirect-to</i> tag of the handler
            configuration are passed to the document.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This redirect-to document can contain a form for the user
            authentication. This form should invoke the real login document which is
            described below.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The authentication process is done by the "auth-login" action.
            The login resource contains this action: </font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="login"&gt;
    &lt;map:act type="auth-login"&gt;
      &lt;map:parameter name="handler" value="unique"/&gt;
      &lt;map:parameter name="parameter_userid" value="{request:name}"/&gt;
      &lt;map:parameter name="parameter_password" value="{request:password}"/&gt;
      &lt;map:redirect-to uri="authentication-successful"/&gt;
    &lt;/map:act&gt;
    &lt;!-- authentication failed: --&gt;
    &lt;map:generate src="auth_failed.xml"/&gt;
    &lt;map:transform src="tohtml.xsl"/&gt;
    &lt;map:serialize/&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>auth-login</i> action uses the handler parameter to call the
            authentication resource of this handler. This authentication resource needs to
            know the information provided by the user. For each piece of information an own
            parameter is created which name starts with "parameter_". So in the example
            above, the authentication resource gets two parameters: userid and password. As
            the values for these parameters were send by a form they need to be passed on
            to the authentication resource. If you use "{request:...}" for the value of a
            parameter, the <i>auth-login</i> action will pass the actual value of that request
            parameter to the authentication resource (by using the input modules concept
            of Cocoon).</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the user is not already authenticated with this handler, the framework calls
            the authentication resource and passes it the parameters. If this
            authentication is successful, the action returns a map and the sitemap
            commands inside the map:act are executed. If the authentication fails, these
            are skipped.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the authentication is successful, a session object is created on
            the server (if not already done). If the authentication fails, the error
            information delivered by the authentication resource is stored into the
            <i>temporary</i> context (which is named simply 'temp').</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The authentication resource</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The last chapters described the authentication process but left out
            details about the authentication itself. This chapter closes this gap.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The authentication can be done by different components:</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">A sitemap resource.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">A distant resource, e.g. requested via HTTP.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">A java class.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using this flexible approach nearly any kind of authentication is
            possible (e.g. database, LDAP). The authentication resource is another
            mandatory configuration of the authentication handler:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;autentication-manager&gt;
    &lt;handlers&gt;
      &lt;!-- Now follows the handlers configuration --&gt;
      &lt;handler name="unique"&gt;
        &lt;redirect-to uri="cocoon:raw://loginpage"/&gt;  &lt;!-- The login resource --&gt;
        &lt;authentication uri="cocoon:raw://authenticationresource"/&gt;
      &lt;/handler&gt;
    &lt;/handlers&gt;
  &lt;/autentication-manager&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the authentication resource is a sitemap resource or a remote
            resource, this resource is requested by the framework with the given parameters from
            the <i>auth-login</i> action (see previous chapter: parameters: userid and
            password). In addition all parameters inside the <i>authentication</i> tag of
            the handler configuration are passed to the resource. The response for this
            resource must contain valid XML conforming to the following scheme:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;authentication&gt;
      &lt;ID&gt;value&lt;/ID&gt;
      &lt;role&gt;rolename&lt;/role&gt; &lt;!-- optional --&gt;
      &lt;data&gt;
          ... resource specific data for the user
      &lt;/data&gt;
  &lt;/authentication&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The framework checks the response of the authentication resource for the
            given scheme: the root node must be named "authentication" and one child called
            "ID" must be present. In this case the authentication is successfull and
            the framework creates an authentication session context and stores the XML inside. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The mandatory information inside this XML scheme, the "ID" tag, is
            an unique identification for the given user inside the web application. The
            "role" is optional and can for example be used for categorizing users and
            displaying different functionality inside the Cocoon portal
            engine).</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the "data" node the authentication resource can pass any
            information of the user into the session object.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the authentication is not successful, the resource must create
            an XML with the root node "authentication". In addition a "data" node can be
            added containing more information about the unsuccessful attempt. This data
            node is then added inside the "login" tag of the login resource (see previous
            chapter).</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Logging out</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The logout process is triggered by the "auth-logout"
            action:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:act type="auth-logout"&gt;
    &lt;map:parameter name="handler" value="unique"/&gt;
  &lt;/map:act&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This action logs the user out of the given handler and removes all
            information about this handler stored in the session.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Working With subsitemaps</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The common solution for the framework and subsitemaps is to define the
            handler (in the main sitemap. The documents
            in the subsitemap are then simply protected in the same way as if the action
            were declared in the main sitemap. This makes moving resources from one sitemap
            to the other very simple.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><b>However, there is one drawback with this solution. After
            you have started your server, make sure that first a resource using the framework
            from the main sitemap is invoked, before any of the subsitemap!</b></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><b>The definition of handlers in a sub-sitemap is a TODO and will be
             available in the next release.</b></font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">User Management</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition to the authentication the framework manages all kinds of
          information belonging to the user in XML format. For this reason the framework
          creates an own session context called "authentication". All information is stored in
          this context.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The authentication information (the "authentication" scheme retrieved
          from the authentication resource) is stored in this context, so you can
          retrieve and change the information using the session transformer and the
          usual getxml, setxml etc. commands, so we suggest you to read the session
          context document.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting information from the context</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each information from within the context is gettable using an XML
            tag:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;session:getxml context="authentication" path="/authentication/ID"/&gt; &lt;!-- Get the ID --&gt;
  &lt;session:getxml context="authentication" path="/authentication/data/username"/&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The path expression is an absolute XPath-like expression where only
            concrete nodes and attributes are allowed. The session transformer replaced
            the tag with the value of the first node found in the context, this can either
            be text or XML.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Setting information in the context</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using another tag information can be stored into the
            context:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;session:setxml context="authentication" path="/authentication/data/usersername"&gt;
      Mr. Sunshine
  &lt;/session:setxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Again the path is an absolute XPath-like expression where only
            concrete nodes and attributes are allowed. If the requested node exists,
            the framework changes the value of that node. If the node does not exists, the framework
            adds it to the context with the given value.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The tag is removed from the resource.</font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Application Management</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A very useful feature for building and maintaining web applications
          is the application management. It allows to configure different
          applications and to manage the user data for these applications.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Configuring an Application</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A "authentication" application is related to one authentication handler, so an
            application is part of the authentication handler configuration:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;autentication-manager&gt;
      &lt;handlers&gt;
          &lt;handler name="unique"&gt;
               ....redirect-to/authentication configuration
               &lt;applications&gt; &lt;!-- the applications for this handler --&gt;
                   &lt;application name="unique"&gt;
                       &lt;load uri="loadapp"/&gt; &lt;!-- optional --&gt;
                       &lt;save uri="saveapp"/&gt; &lt;!-- optional --&gt;
                   &lt;/application&gt;
               &lt;/applications&gt;
          &lt;/handler&gt;
      &lt;/handlers&gt;
  &lt;/autentication-manager&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A configuration for an application consists of a unique name (only
            alphabetical characters and digits are allowed for the application name) and
            optional load and save resources. The application configuration can contain
            application specific configuration values for the various parts of the
            application, e.g. information for a portal.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">On a successful authentication the framework invokes for each application
            of the handler the load resource (if present). The content or result of the
            load resource is stored into the session context.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The user does not always visit all sides or all applications at
            once. So it is not necessary to load all applications in advance when not all
            information is needed. Each application can specify if the data is loaded on
            successful authentication or the first time needed:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>....&lt;application name="unique" loadondemand="true"/&gt;...</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The load resource gets several parameters: all values of the
            subnodes of the "authentication" node from the authentication context (e.g. ID, role
            etc.) and the parameter "application" with the unique name of the application.
            This unique name must not contain one of the characters '_', ':' or '/'.</font>
  </p>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition the load and save resource get all parameters specified
            inside the load / save tag of the handler configuration.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Configuring the resources</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For managing the application the framework needs to know to which
            application a resource belongs. So in addition to the handler parameter the
            auth-protect action gets the application name as a second parameter:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="protectedresource"&gt;
    &lt;map:action type="auth-protect"&gt;
      &lt;map:parameter name="handler" value="unique handler name"/&gt;
      &lt;map:parameter name="application" value="unique application name"/&gt;
      
      &lt;map:generate src="source/resource.xml"/&gt;
              ...
    &lt;/map:action&gt;
  &lt;/map:match&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">With this mechanism each application resource can easily access its
            and only its information. If a resource has no "application" parameter it can
            not access information of any application.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting, setting and saving application information</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Analogue to the access of the authentication data a resource can
            access its application data:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;session:getxml context="authentication" path="/application/username"/&gt;
  &lt;session:setxml context="authentication"  path="/application/shoppingcart"&gt;&lt;item1/&gt;&lt;item2/&gt;&lt;/session:setxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The path underlies the same restrictions and rules as always, but
            it has to start with "/application/". </font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Module Management</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition to the application management the framework offers a facility
          called module management. It enhances the application management by the
          possibility to configure components for the application. For example the Cocoon
          portal engine needs information about where the portal profile
          for the user is retrieved from, where the layout is stored etc. Now each portal
          needs this information. Assuming that a portal is an application each
          application needs this information. As only the portal engine itself knows what
          information it needs, the module management is a standarized way for
          configuring such components.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The module configuration is part of the application
          configuration:</font>
  </p>
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;autentication-manager&gt;
    &lt;handlers&gt;
      &lt;handler name="unique"&gt;
        ....redirect-to/authentication configuration
        &lt;applications&gt;  &lt;!-- the applications for this handler --&gt;
          &lt;application name="unique"&gt;
            ...
            &lt;configuration name="portal"&gt;
              ...portal configuration
            &lt;/configuration&gt;
          &lt;/application&gt;
        &lt;/applications&gt;
      &lt;/handler&gt;
    &lt;/handlers&gt;
  &lt;/autentication-manager&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">So whenever the portal engine is asked to build the portal it can
          easily retrieve its configuration from the current application by getting the
          module configuration named "portal".</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">User Administration</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the framework it is possible to add new roles to the system and to
          add new users. For this purpose, there are several optional entries for the
          authentication handler which provide the needed functionality:</font>
  </p>
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;autentication-manager&gt;
    &lt;handlers&gt;
      &lt;handler name="unique"&gt;
               ...redirect-to/authentication configuration...
  
        &lt;!-- Optional resource for loading user information --&gt;
        &lt;load-users uri="cocoon:raw://financeresource-sunrise-loaduser"/&gt;
  
        &lt;!-- Optional resource for loading roles information--&gt;
        &lt;load-roles uri="cocoon:raw://financeresource-sunrise-roles"/&gt;
  
        &lt;!-- Optional resource for creating a new user --&gt;
        &lt;new-user uri="cocoon:raw://financeresource-sunrise-newuser"/&gt;
  
        &lt;!-- Optional resource for creating a new role --&gt;
        &lt;new-role uri="cocoon:raw://financeresource-sunrise-newrole"/&gt;
  
        &lt;!-- Optional resource for changing user information --&gt;
        &lt;change-user uri="cocoon:raw://financeresource-sunrise-newuser"/&gt;
  
        &lt;!-- Optional resource for deleting a role --&gt;
        &lt;delete-role uri="cocoon:raw://financeresource-sunrise-delrole"/&gt;
  
        &lt;!-- Optional resource for deleting a user--&gt;
        &lt;delete-user uri="cocoon:raw://financeresource-sunrise-deluser"/&gt;
      &lt;/handler&gt;
    &lt;/handlers&gt;
  &lt;/autentication-manager&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The entries are described in the following subchapters. All tags can
          have additional parameter definitions which are passed to the given resource,
          e.g:</font>
  </p>
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;!-- Optional resource for deleting a user--&gt;
  &lt;delete-user uri="cocoon:raw://financeresource-sunrise-deluser"&gt;
    &lt;connection&gt;database&lt;/connection&gt;
    &lt;url&gt;db:usertable&lt;/url&gt;
  &lt;/delete-user&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting Roles</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>load-roles</i> resource is invoked from the framework whenever
            it needs information about the available roles. This resource gets the
            parameter "type" with the value "roles" and should deliver an XML schema with
            the root node "roles" and for each role a subelement "role" with a text child
            of the rolename:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;roles&gt;
    &lt;role&gt;admin&lt;/role&gt;
    &lt;role&gt;guest&lt;/role&gt;
    &lt;role&gt;user&lt;/role&gt;
  &lt;/roles&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting Users</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>load-users</i> resource is called whenever information
            about the available users is needed. There are three different uses of this
            resource:</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">Loading all users: The resource gets the parameter "type"
               with the value "users". It should then deliver all users in the system.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Loading all users of one role. The resource gets the
               parameters "type" with the value "users" and "role" with the rolename.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Load information of one user. The resource gets the
               parameters "type" with the value "user", "role" with the rolename and "ID" with
               the authentication ID of the user.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The XML format of the resource should look like the
            following:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;users&gt;
    &lt;user&gt;
      &lt;ID&gt;authentication ID&lt;/ID&gt;
      &lt;role&gt;rolename&lt;/role&gt;
      &lt;data&gt;
         ... application specific data ...
      &lt;/data&gt;
    &lt;/user&gt;
    &lt;user&gt;
      ...
    &lt;/user&gt;
      ...
  &lt;/users&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Creating a new role</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>new-role</i> resource creates a new role in the system. It
            gets the parameters "type" with the value "role" and "role" with the new
            rolename.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Creating a new user</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>new-user</i> resource creates a new user with a role. It
            gets the parameters <i>"type"</i> with the value <i>"user"</i>,
            <i>"role"</i> with the rolename and <i>"ID"</i> with the new ID for this
            user.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Changing information of a user</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>change-user</i> resources changes information of a user.
            It gets the parameters "type" with the value "user", "role" with the rolename
            and "ID" with the ID of the user. In addition all - application specific -
            information of this user is send as parameters.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Delete a user</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>delete-user</i> resource should delete a user. It gets the
            parameters "type" with the value "user", "role" with the rolename and "ID" with
            the ID of the user.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Delete a role</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>delete-role</i> resources deletes a role. It gets the
            parameters "type" with the value "role" and "role" with the rolename .</font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Configuration Summary</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Here is a brief summary of the authentication handler configuration: </font>
  </p>
  
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;autentication-manager&gt;
    &lt;handlers&gt;
      &lt;handler name="unique"&gt;
        &lt;redirect-to uri="cocoon:raw://loginpage"/&gt; &lt;!-- The redirect-to resource --&gt;
        &lt;authentication uri="cocoon:raw://authenticationresource"/&gt; &lt;!-- Authentication resource --&gt;
  
        &lt;load uri="cocoon:raw://authenticationsaveresource"&gt;
          &lt;!-- optional parameters --&gt;
        &lt;/load&gt;
        &lt;!-- optional save resource --&gt;
        &lt;save uri="cocoon:raw://authenticationsaveresource"&gt;
          &lt;!-- optional parameters --&gt;
        &lt;/save&gt;
  
        &lt;applications&gt;
          &lt;!-- the applications for this handler --&gt;
          &lt;application name="unique"&gt;
  
            &lt;!-- Loading/Saving --&gt;
            &lt;load uri="cocoon:raw://loadapp"&gt;
              &lt;!-- optional --&gt;
              &lt;!-- optional parameters --&gt;
            &lt;/load&gt;
            &lt;save uri="cocoon:raw://saveapp"&gt;
              &lt;!-- optional --&gt;
              &lt;!-- optional parameters --&gt;
            &lt;/save&gt;
            &lt;!-- module configurations: --&gt;
  
            &lt;configuration name="portal"&gt;
              ...portal configuration
            &lt;/configuration&gt;
          &lt;/application&gt;
        &lt;/applications&gt;
  
      &lt;/handler&gt;
    &lt;/handlers&gt;
  &lt;/autentication-manager&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Pipeline Patterns</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">As explained in the previous chapters, the framework uses the <i>auth-protect</i>
          action for authentication and protecting documents. This chapter shows some
          common used pipeline patterns for using this framework.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Single protected document</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For protecting a document with an authentication handler only the <i>auth-protect</i>
            action with the parameter configuration for the handler is required.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Pattern:</font>
  </p>
          
  <blockquote>
  <ol>
            
  <li>
  <font face="verdana, helvetica, sans serif">Pipeline matching
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Using the <i>auth-protect</i> action for protecting
            </font>
  </li>
          
  </ol>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Example:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="protected"&gt;
    &lt;map:act type="auth-protect"&gt;  &lt;!-- protect the resource --&gt;
      &lt;map:parameter name="handler" value="myhandler"/&gt;
  
      &lt;map:generate src="resource.xml"/&gt;
      &lt;map:transform src="toHTML"/&gt;
      &lt;map:serialize/&gt;
    &lt;/map:act&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">It is very important that the <i>auth-protect</i> action wrapps the real
            pipeline, as the pipeline is only invoked if the action grants access. The
            matching must be done before the action is checked as the action performs a
            redirect for this document.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Multiple protected documents</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Often you want to protect a bunch of documents in the same way. One
            solution is to use the single protected document pattern for each document.
            With the multiple protected document pattern you only have to use the action
            once for all documents and not within each document pipeline.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The prerequisite for this is a common matching pattern for the
            documents:</font>
  </p>
          
  <blockquote>
  <ol>
            
  <li>
  <font face="verdana, helvetica, sans serif">Pipeline pattern matching
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Using the <i>auth-protect</i> action for protection
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Pipeline matching
            </font>
  </li>
          
  </ol>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Example:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="protected-*"&gt;
    &lt;map:act type="auth-protect"&gt; &lt;!-- protect the resource --&gt;
      &lt;map:parameter name="handler" value="myhandler"/&gt;
  
      &lt;map:match pattern="protected-first"&gt;
        &lt;map:generate src="resource1.xml"/&gt;
        &lt;map:transform src="toHTML"/&gt;
        &lt;map:serialize/&gt;
      &lt;/map:match&gt;
          ....
      &lt;map:match pattern="protected-second"&gt;
        &lt;map:generate src="resource2.xml"/&gt;
        &lt;map:transform src="toHTML"/&gt;
        &lt;map:serialize/&gt;
      &lt;/map:match&gt;
    
    &lt;/map:act&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Very important - as explained with the single document pattern - is
            the leading match before the action is performed. The second match is required
            to check which pipeline to use.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Controlling the Application Flow</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you want to create documents which behave different wheather you
            are logged in or not, the <i>auth-loggedIn</i> action is the component to
            controll your application flow. This action checks if the user is authenticated
            for a given handler and calls all sitemap components inside the <i>act</i>
            tag.</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="startpage"&gt;
  
    &lt;map:act type="auth-loggedIn"&gt;  &lt;!-- check authentication --&gt;
      &lt;map:parameter name="handler" value="myhandler"/&gt;
  
      &lt;map:redirect-to uri="loggedInStartPage"/&gt;
    &lt;/map:act&gt;
  
    &lt;map:generate src="startpage.xml"/&gt;
    &lt;map:transform src="toHTML"/&gt;
    &lt;map:serialize/&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In the example above, if the user is already logged he is
            redirected to the <i>loggedInStartPage</i> document. If he is not logged in
            for the given handler, the usual start page is generated.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Both actions, the <i>auth-protect</i> and the
            <i>auth-loggedIn</i> action return - if the user is logged in for the
            given handler - all values from the context to the sitemap, e.g. ID, role etc.
            These values can be used within the other components:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern"protected"&gt;
    &lt;map:act type="auth-protect"&gt;  &lt;!-- protect the resource --&gt;
      &lt;map:parameter name="handler" value="myhandler"/&gt;
  
      &lt;!-- Append the ID of the user to the file name --&gt;
      &lt;map:generate src="resource_{ID}.xml"/&gt;
      &lt;map:transform src="toHTML"/&gt;
      &lt;map:serialize/&gt;
  
    &lt;/map:act&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">But the <i>auth-loggedIn</i> action does not give the included pipeline
            access to the authentication context belonging to the handler. If you want this, you
            have to nest the <i>auth-protect</i> action inside!</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern"start"&gt;
  
    &lt;map:act type="auth-loggedIn"&gt;  &lt;!-- check authentication --&gt;
      &lt;map:parameter name="handler" value="myhandler"/&gt;
  
      &lt;map:act type="auth-protect"&gt;  &lt;!-- give access to the context --&gt;
        &lt;map:parameter name="handler" value="myhandler"/&gt;
  
        &lt;map:generate src="getinfofromcontext.xml"/&gt;
        &lt;map:transform src="session"/&gt;
        &lt;map:transform src="toHTML"/&gt;
        &lt;map:serialize/&gt;
      &lt;/map:act&gt;
    &lt;/map:act&gt;
  
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
    
  
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/index.html
  
  Index: index.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>Webapps Developer Documentation</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">Webapps Developer Documentation</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Dev Guide</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Webapps</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Overview</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="authentication.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../howto/xmlform-wizard/howto-xmlform-wizard.html">Form Handling</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="portal.html">Portal</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Scratchpad</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunshine.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunrise.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunspot.html">Portal</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
   
  
   
   <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Overview</font>
  <hr style="color: #0086b2" size="1">
   
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This section contains several documents about developing real-world web applications
    with Cocoon.</font>
  </p>
   
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Some of these concepts are currently in development. The development of the
    <a href="session.html">Session handling</a>, the 
    <a href="authentication.html">authentication</a> framework and
    the <a href="portal.html">portal framework</a> is nearly finished. You will
    find these components in the latest CVS version of Cocoon. The documentation
    listed in the menu conforms to the current CVS version.</font>
  </p>
   
  <p>
  <font color="black" face="verdana,helvetica,sanserif">However, the current release 2.0.3 contains alpha versions in the
     scratchpad area of these three components. So you can already have a look at them. The
     documentation in the "scratchpad" folder contains the description conforming to the
     scratchpad. But be warned that they are in the scratchpad area and will change in 
     upcomming releases. So if you are really planning to use them, have a look at the
     latest CVS.
   </font>
  </p>
  
   
  
   
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/portal.html
  
  Index: portal.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>Building Portals with Cocoon</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">Building Portals with Cocoon</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Dev Guide</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Webapps</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Overview</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="authentication.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../howto/xmlform-wizard/howto-xmlform-wizard.html">Form Handling</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Portal</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Scratchpad</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunshine.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunrise.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunspot.html">Portal</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
      
      
    <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Introduction</font>
  <hr style="color: #0086b2" size="1">
      
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i><b>IMPORTANT:</b> This document conforms to the development version of Cocoon. So
          you will only find these components in the current CVS. An early alpha version is already
          available in the latest release of Cocoon, you will find an introduction <a href="sunspot.html">here</a>.
      </i></font></td>
  </tr>
  </table>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The portal engine of Cocoon provides the required
          functionality to display user dependent content with a user defineable
          layout.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The Cocoon portal defintion framework is an XML description of the
          portal and the contained content. The rendering of the portal to the needed
          format (such as HTML) is done through stylesheets and is therefore very
          flexible.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A portal definition can be configured for all users (global), for
          groups of users (group or role) and for the individual user. The portal
          admininstrator can use the provided tools to configure every aspect of the
          portal (from colours to content).</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each "blob" of portal content is contained in a "coplet" (<i>Co</i>coon <i>p</i>ort<i>let</i>). coplets can
          be configured into the portal on a per-user or per-group basis allowing a
          flexible content definition.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">coplets can be minimized, maximized or even removed by the user if he
          does not wish to see the content. However, the administrator may configure
          coplets to be mandatory, in which case they may not be removed.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The different portals are administrated by authentication applications. Each
          application can have its own portal.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This documentation explains the different resources for the portal, the
          configuration of a portal and how it creates the portal view derived from
          this information. After that all is put together by creating the needed entries
          in the sitemap for using and displaying a portal.</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">The Profile</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A portal is built upon a profile which contains all necessary
          information: the portal possibilites (the available coplets, the possible
          changes to the layout etc.) and the portal view (the layout for this user and
          the coplets he chose for himself). This profile is generated when a user logs
          into the application the portal belongs to. The building of the profile is a
          very flexible process which allows to have different configurations for
          different users.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In general the building of the profile consists of four steps:</font>
  </p>
       
  <blockquote>
  <ol>
          
  <li>
  <font face="verdana, helvetica, sans serif">Building the base profile. This profile defines which
            possibilites the portal has, which coplets are available to the portal and
            which parts of the profile can be changed by the user.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">Building the global profile. The base profile is enhanced by a
            global delta which contains a predefined portal view. This predefined portal
            view is a starting point for all users.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">Building the role profile. The global profile is enhanced by a
            role delta which contains a predefined portal view. This predefined portal view
            is a starting point for all users of that role.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">Building the user profile. The role profile is augmented by a
            user delta which contains the portal for this specific user. An optional user
            status profile with often changing information can optional be appended to the
            profile.
          </font>
  </li>
       
  </ol>
  </blockquote>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Only step 1 and 2 are mandatory for the building process. Steps 3 and
          4 are optional and depend on the configuration of the users and roles in the
          system.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each delta (steps 2, 3 and 4) can modify the possibilites of the
          portal and the configuration of the coplets. But it is not allowed to add new
          features or coplets. In addition a delta may contain a predefined portal
          view.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This building process is invoked each time the user logs into the
          application. So a change to any profile (delta) is incorporated into the user
          profile: If e.g. a coplet , which a user has choosen for his portal view, is
          removed from the system, it is not available to the user anymore and therefore
          also removed from his portal view.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The global delta, the role delta and the user delta are very similar.
          They only differ in the name of the root node.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Base Profile</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The base profile consists of three data sources:</font>
  </p>
          
  <blockquote>
  <ol>
            
  <li>
  <font face="verdana, helvetica, sans serif"> The layout profile describes the possibilites and layout of
               the portal.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The coplets profile defines all available coplets for the
               portal view.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The type profile describes the parts of the profile which can
               be changed by the user.
            </font>
  </li>
          
  </ol>
  </blockquote>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The Layout Profile</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The layout profile describes the overall layout of the portal
               including if header or footer are present which colors and fonts are used and
               so on.</font>
  </p>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">An example profile is shown below. The profile is enclosed in the
               root node "layout-profile" and consists of the "portal" part and the "coplets"
               part:</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;layout-profile&gt;
    &lt;portal&gt;
      &lt;!-- This node contains the layout of the portal view --&gt;
      &lt;layouts&gt;
        &lt;layout&gt;
          &lt;!-- The color of the background --&gt;
          &lt;background&gt;
            &lt;color&gt;#ffffff&lt;/color&gt;
          &lt;/background&gt;
          &lt;!-- The font and color for usual text --&gt;
          &lt;font&gt;
            &lt;type&gt;Arial, Helvetica, sans-serif&lt;/type&gt;
            &lt;size&gt;2&lt;/size&gt;
            &lt;color&gt;black&lt;/color&gt;
          &lt;/font&gt;
        &lt;/layout&gt;
      &lt;/layouts&gt;
      &lt;!-- The following means that the portal has a header area --&gt;
      &lt;header&gt;
        &lt;exists&gt;true&lt;/exists&gt;
      &lt;/header&gt;
      &lt;!-- The following means that the portal has 3 columns --&gt;
      &lt;columns&gt;
        &lt;number&gt;3&lt;/number&gt;
      &lt;/columns&gt;
      &lt;!-- The following means that the portal has not a footer area --&gt;
      &lt;footer&gt;
        &lt;exists&gt;false&lt;/exists&gt;
      &lt;/footer&gt;
    &lt;/portal&gt;
    &lt;coplets&gt;
      &lt;!-- This node contains the layout of the coplets --&gt;
      &lt;layouts&gt;
        &lt;layout&gt;
          &lt;title&gt;
            &lt;!-- The layout of the title --&gt;
            &lt;background&gt;
              &lt;color&gt;#46627A&lt;/color&gt;
            &lt;/background&gt;
            &lt;font&gt;
              &lt;type&gt;Arial&lt;/type&gt;
              &lt;size&gt;2&lt;/size&gt;
              &lt;color&gt;#ffffff&lt;/color&gt;
            &lt;/font&gt;
          &lt;/title&gt;
          &lt;content&gt;
            &lt;!-- The layout of the content --&gt;
            &lt;font&gt;
              &lt;type&gt;Arial&lt;/type&gt;
              &lt;size&gt;2&lt;/size&gt;
              &lt;color&gt;#000000&lt;/color&gt;
            &lt;/font&gt;
            &lt;background&gt;
              &lt;color&gt;#ffffff&lt;/color&gt;
            &lt;/background&gt;
          &lt;/content&gt;
        &lt;/layout&gt;
      &lt;/layouts&gt;
    &lt;/coplets&gt;
  &lt;/layout-profile&gt;
          </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The coplets Profile</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The coplets profile contains all coplets which are available in
               the system. It is an XML based resource with the root node "coplets-profile".
               All coplets are defined under a node called "coplets", so an example profile
               could look like this:</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>    &lt;coplets-profile&gt;
    &lt;coplets&gt;
      &lt;coplet id="bankingnews"&gt;
        &lt;resource uri="cocoon://coplet-banking.xml"/&gt;
        &lt;transformation&gt;
          &lt;!-- optional xsl transformation --&gt;
          &lt;stylesheet&gt;sunbank/styles/coplet.xsl&lt;/stylesheet&gt;
        &lt;/transformation&gt;
        &lt;configuration&gt;
          &lt;mandatory&gt;false&lt;/mandatory&gt;
          &lt;sizable&gt;true&lt;/sizable&gt;
          &lt;active&gt;true&lt;/active&gt;
          &lt;timeout&gt;5000&lt;/timeout&gt;
          &lt;!-- optional, milliseconds --&gt;
          &lt;messages&gt;
            &lt;!-- optional: Messages --&gt;
            &lt;coplet_not_available&gt;
                             Display this if the coplet is not available.
                          &lt;/coplet_not_available&gt;
          &lt;/messages&gt;
        &lt;/configuration&gt;
        &lt;title&gt;Banking News&lt;/title&gt;
        &lt;status&gt;
          &lt;visible&gt;true&lt;/visible&gt;
          &lt;size&gt;max&lt;/size&gt;
        &lt;/status&gt;
      &lt;/coplet&gt;
    &lt;/coplets&gt;
  &lt;/coplets-profile&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This example defines one coplet: the bankingnews coplet with the
               title "Banking News". The title is displayed in the portal view above the
               coplet content. The most important part is the resource definition. Using this
               resource the coplet is displayed in the portalview of the user. </font>
  </p>
            
  <blockquote>
  <ul>
               
  <li>
  <font face="verdana, helvetica, sans serif">An uri, e.g.: &lt;resource uri=".."/&gt;. This URI can be a
                  local one which is retrieved using the sitemap or a distant one which is
                  retrieved using an HTTP request. In both cases the resource must deliver valid
                  XML for the coplet content. If you don't use a protocol, the URI is assumed to
                  be a file.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">A java class delivering the content.
               </font>
  </li>
            
  </ul>
  </blockquote>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">There a several mandatory configuration parameters for a coplet.
               This configuration parameters can only be changed by the portal administrator.
               The user cannot change them for his portal view.</font>
  </p>
            
  <blockquote>
  <ul>
               
  <li>
  <font face="verdana, helvetica, sans serif">mandatory: Indicates if the coplet can be removed by the
                  user or if it is always visible.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">sizable: Is the coplet sizable? If the value is true the
                  user can minimize this coplet in his portal view.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">active: Using this parameter, a coplet can be deactivated
                  for a distinct period of time. If a coplet is not active it will not displayed
                  to the user even if he has configured it.
               </font>
  </li>
            
  </ul>
  </blockquote>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition there are some optional parameters:</font>
  </p>
            
  <blockquote>
  <ul>
               
  <li>
  <font face="verdana, helvetica, sans serif">timeout: This is the time in milliseconds, the portal waits to
                  get the coplet content. If the content is not available within this time frame,
                  the coplet is declared as not available at the moment. The default value for
                  the timeout can be set in the portal configuration (see next chapter).
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">handlesSizable: If this value is true, the coplet (or
                  better the resource) handles the sizing of this coplet itselt. This means it
                  determines the data to be displayed if the coplet is minimized or maximized. If
                  this value is false the portal displayes the whole coplet if it is maximized and
                  only its title if it is minimized. This is the default behaviour.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">handlesParameters: If this value is true (which is the
                  default value) the resource gets all configuration and status parameters
                  passed, e.g. if the resource is an uri, the parameters are passed as HTTP
                  request parameters.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">messages/coplet_not_available: If the coplet is not
                  available (e.g. external data where the server is not available), a message is
                  displayed. With this optional parameter each coplet can get a distinct message
                  which overrides the message provided by the user profile.
               </font>
  </li>
            
  </ul>
  </blockquote>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The status parameters can be changed by the user for configuring
               his own portal view:</font>
  </p>
            
  <blockquote>
  <ul>
               
  <li>
  <font face="verdana, helvetica, sans serif">visible: If a coplet is visible it is included in the
                  portal view. If it is not visible it is still configured for the user but it
                  will not displayed.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">size: Currently two sizes (min and max) are distinquished.
               </font>
  </li>
            
  </ul>
  </blockquote>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the source of the coplet needs additional transformation there
               are two possibilities for doing the transformation. The first one is creating a
               pipeline in the sitemap for this coplet and the second one usses the coplet
               configuration for this. As the first one is the usual pipeline
               creating process only the second one is covered here.</font>
  </p>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">By defining the "transformation" node inside the "coplet" node,
               the source of the coplet can be transformed with one or more stylesheets. For
               each stylesheet a "stylesheet" node with the value of the stylesheet path has
               to be created. The order of appearance determines the order of processing. If
               e.g. the source of a coplet is a class or a file, there is no need to specify a
               pipeline only for this coplet. Specifying a file/class as source and a
               "stylesheet" node has the same effect.</font>
  </p>
            
  <font face="verdana, helvetica, sans serif" color="#0086b2"><b>Adding a new coplet</b></font>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Adding new information to the portal requires four basic
                  steps:</font>
  </p>
               
  <blockquote>
  <ul>
                  
  <li>
  <font face="verdana, helvetica, sans serif">Defining the resource containing the information. For
                    external resources only the address (mainly an URI) and the protocol (usually
                    HTTP) is required. Otherwise a new XML resource has to be created with the new
                    content.
                  </font>
  </li>
                  
  <li>
  <font face="verdana, helvetica, sans serif">Defining the stylesheet for the presentation of this
                    content.
                  </font>
  </li>
                  
  <li>
  <font face="verdana, helvetica, sans serif">For local resources: Definition of the pipeline in the
                    sitemap. This pipeline must contain all necessary steps for building the
                    information. It must deliver XML as the serialized format.
                  </font>
  </li>
                  
  <li>
  <font face="verdana, helvetica, sans serif">Adding a new "coplet" node to the coplets profile.
                  </font>
  </li>
               
  </ul>
  </blockquote>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">After these steps are finished, the new coplet is automatically
                  available for each user which logs in after the addition. If the coplet is even
                  mandatory it will be added to the portal view of the user.</font>
  </p>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For more information see the chapter "The Pipelines".</font>
  </p>
            
            
  <font face="verdana, helvetica, sans serif" color="#0086b2"><b>Customizable coplets</b></font>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each coplet can have its own configuration, e.g. a weather
                  coplet should display the weather for a particular city etc.</font>
  </p>
               
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>    &lt;coplets-profile&gt;
    &lt;coplets&gt;
      &lt;coplet id="bankingnews"&gt;
        &lt;resource uri="cocoon://coplet-banking.xml"/&gt;
        &lt;customization uri="cocoon://customize-coplet-banking.xml"/&gt;
        &lt;!-- optional --&gt;
        &lt;transformation&gt;
          &lt;!-- optional xsl transformation --&gt;
          &lt;stylesheet&gt;sunbank/styles/coplet.xsl&lt;/stylesheet&gt;
        &lt;/transformation&gt;
        &lt;configuration&gt;
          &lt;mandatory&gt;false&lt;/mandatory&gt;
          &lt;sizable&gt;true&lt;/sizable&gt;
          &lt;active&gt;true&lt;/active&gt;
          &lt;timeout&gt;5000&lt;/timeout&gt;
          &lt;!-- optional, milliseconds --&gt;
          &lt;messages&gt;
            &lt;!-- optional: Messages --&gt;
            &lt;coplet_not_available&gt;
                             Display this if the coplet is not available.
                          &lt;/coplet_not_available&gt;
          &lt;/messages&gt;
          &lt;customizable&gt;true&lt;/customizable&gt;
          &lt;!-- optional --&gt;
          &lt;persistent&gt;false&lt;/persistent&gt;
          &lt;!-- optional --&gt;
        &lt;/configuration&gt;
        &lt;title&gt;Banking News&lt;/title&gt;
        &lt;status&gt;
          &lt;visible&gt;true&lt;/visible&gt;
          &lt;size&gt;max&lt;/size&gt;
        &lt;/status&gt;
      &lt;/coplet&gt;
    &lt;/coplets&gt;
  &lt;/coplets-profile&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">To declare a coplet as customizable it must get a configuration
                  resource which is displayed to a user of this coplet to enter all required
                  configuration values. This is done with the <i>customization</i> tag. The
                  value for this tag has the same possibilities as the <i>resource</i> tag,
                  usually the <i>uri</i> attribute points to a pipeline.</font>
  </p>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">When a user has configured/choosen a customizable coplet,
                  the portal detects if this coplet has its configuration. If it does not have one,
                  the customization resource of the coplet is displayed in the portal view.
                  Otherwise the coplet itself is displayed.</font>
  </p>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition a customizable coplet can be persistent, e.g. the
                  configuration is saved for a longer period than the current session of the
                  user. If the coplet is not persistent the configuration is lost when the user
                  logs out. The next time he logs in, the customization page is displayed to
                  configure this coplet again.</font>
  </p>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you use persistent coplets you have to configure resources
                  for loading and saving the status profile (See configuration). More about
                  writing customizable coplets can be found in the chapter "Writing Customizable
                  coplets".</font>
  </p>
            
          
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The Type Profile</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The type profile describes the possible values the user can
               change for his portal view. Using this flexible approach the portal
               administrator can decide which user can choose what. For example, a normal user
               might change the layout and content of his portal view, but a guest might not
               be allowed to change anything, whereas the administrator can change
               everything.</font>
  </p>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The type profile is surrounded by the root node "type-profile".
               It consists of two parts: the typedefs section and the elements section. The
               type profile can be compared with a programming language. The typedefs section
               declares all available types and the the elements section declares all
               variables with their corresponding types. A "variable" defines a place or
               element in the user profile which can be changed by the user. The possibilites
               for this element are defined by the type.</font>
  </p>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The typedefs contains enumerations, e.g. a set of possible values
               with a user presentable name. In addition the portal has the following predefined
               types: STRING (arbitrary text), BOOLEAN (true or false), INTEGER (a number) and
               CARDINAL (a positiv number).</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;type-profile&gt;
    &lt;typedefs&gt;
      &lt;!-- The following types are defined by the portal: (Names are casesensitiv!)
                            STRING, BOOLEAN, ENUMERATION, INTEGER, CARDINAL --&gt;
      &lt;typedef name="backgroundcolor" type="ENUMERATION"&gt;
        &lt;value name="weiss"&gt;#ffffff&lt;/value&gt;
        &lt;value name="hellgrau"&gt;#cccccc&lt;/value&gt;
        &lt;value name="hellgruen"&gt;#aab9bf&lt;/value&gt;
        &lt;value name="dunkelgruen"&gt;#46627A&lt;/value&gt;
      &lt;/typedef&gt;
      &lt;typedef name="textcolor" type="ENUMERATION"&gt;
        &lt;value name="weiss"&gt;white&lt;/value&gt;
        &lt;value name="schwarz"&gt;black&lt;/value&gt;
        &lt;value name="weiss"&gt;#ffffff&lt;/value&gt;
        &lt;value name="hellgrau"&gt;#cccccc&lt;/value&gt;
        &lt;value name="hellgruen"&gt;#aab9bf&lt;/value&gt;
        &lt;value name="dunkelgruen"&gt;#46627A&lt;/value&gt;
      &lt;/typedef&gt;
      &lt;typedef name="copletsize" type="ENUMERATION"&gt;
        &lt;value name="Maximized"&gt;max&lt;/value&gt;
        &lt;value name="Minimized"&gt;min&lt;/value&gt;
      &lt;/typedef&gt;
      &lt;typedef name="columnnumber" type="ENUMERATION"&gt;
        &lt;value name="1"&gt;1&lt;/value&gt;
        &lt;value name="2"&gt;2&lt;/value&gt;
        &lt;value name="3"&gt;3&lt;/value&gt;
        &lt;value name="4"&gt;4&lt;/value&gt;
        &lt;value name="5"&gt;5&lt;/value&gt;
      &lt;/typedef&gt;
    &lt;/typedefs&gt;
  &lt;/type-profile&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The element section has the same structure a the user profile.
               For each leave which is changeable by the user the elements section contains an
               entry for the type of this node. The node is enhanced by two attributes: type
               for the node type and description for a user readable title. This information
               is used by the portal to present the configuration screen for the portal. It
               displayes for each changeable leave a form field with the corresponding
               type.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;type-profile&gt;
    &lt;elements&gt;
      &lt;layout-profile&gt;
        &lt;portal&gt;
          &lt;layouts&gt;
            &lt;layout&gt;
              &lt;!-- The user can change the background.
                            The possible values are taken from the enumeration
                            backgroundcolor. The user gets the title "Background"
                            displayed for the form field. --&gt;
              &lt;background&gt;
                &lt;color type="backgroundcolor" description="Background"/&gt;
              &lt;/background&gt;
              &lt;font&gt;
                &lt;color type="textcolor" description="Font color"/&gt;
              &lt;/font&gt;
            &lt;/layout&gt;
          &lt;/layouts&gt;
          &lt;columns&gt;
            &lt;!-- The user can change the number of columns --&gt;
            &lt;number type="columnnumber" description="Number of columns"/&gt;
          &lt;/columns&gt;
        &lt;/portal&gt;
      &lt;/layout-profile&gt;
      &lt;portal-profile&gt;
        &lt;content&gt;
          &lt;!-- Using the * the following configuration is applied for
                        all columns regardless of their position. --&gt;
          &lt;column position="*"&gt;
            &lt;width type="CARDINAL" description="Width"/&gt;
            &lt;coplets&gt;
              &lt;!-- Using the * the following configuration is applied for
                                each coplet. --&gt;
              &lt;coplet id="*" position="*" number="*"&gt;
                &lt;status&gt;
                  &lt;!-- The user can change the visibility and size
                                    of the coplet --&gt;
                  &lt;visible type="BOOLEAN" description="Visible"/&gt;
                  &lt;size type="copletsize" description="Size"/&gt;
                &lt;/status&gt;
              &lt;/coplet&gt;
            &lt;/coplets&gt;
          &lt;/column&gt;
        &lt;/content&gt;
      &lt;/portal-profile&gt;
    &lt;/elements&gt;
  &lt;/type-profile&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Global Profile</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The global delta, the role delta and the user delta are very
            similar. They only differ in the name of the root node. So this chapter only
            describes the global delta and points out the differences between the deltas at
            the various place rather than repeating the same information in different
            chapters.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The global delta is enclosed in the root node "global-delta", the
            role delta uses the node "role-delta" and the user delta the node
            "user-delta".</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In general a delta defines the differences between two profiles.
            The portal deltas allow only adding and changing but not removing nodes. Each
            delta can contain the following parts: </font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">The layout delta containing the difference to the layout
               profile.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The coplets delta describing the differences to the coplets
               profile.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The portal profile containing a complete portal view. This
               part is not a delta. If it is contained in a delta and the profile already has
               this information, that information is replaced by the one from the delta.
               Otherwise the delta information is added. For the global profile the portal
               profile is mandatory.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The personal profile. This part contains personal information
               of the user, e.g. are welcome text. For the global profile this information
               again is mandatory. It defines the possibilites the user has. The role and the
               user profile can only change this information. But they cannot add any new
               nodes.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"> So here is an example:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;global-delta&gt;
    &lt;!-- No difference to the base profile --&gt;
    &lt;layout-delta/&gt;
    &lt;!-- No difference to the base profile --&gt;
    &lt;coplets-delta/&gt;
    &lt;!-- This is the starting portal view for all users.
           It has to be defined in the global profile --&gt;
    &lt;portal-profile&gt;
      &lt;!-- This is the content of the portal view --&gt;
      &lt;content&gt;
        &lt;header&gt;
          &lt;coplet id="personalize" position="1"&gt;
            &lt;status&gt;
              &lt;visible&gt;true&lt;/visible&gt;
              &lt;size&gt;max&lt;/size&gt;
            &lt;/status&gt;
          &lt;/coplet&gt;
        &lt;/header&gt;
        &lt;column position="1"&gt;
          &lt;width&gt;28%&lt;/width&gt;
          &lt;!-- The coplets are displayed in the order of their
                       position attribute in each column. --&gt;
          &lt;coplets&gt;
            &lt;coplet id="administration" number="1" position="1"&gt;
              &lt;status&gt;
                &lt;visible&gt;true&lt;/visible&gt;
                &lt;size&gt;max&lt;/size&gt;
              &lt;/status&gt;
            &lt;/coplet&gt;
          &lt;/coplets&gt;
        &lt;/column&gt;
        &lt;column position="2"&gt;
          &lt;width&gt;50%&lt;/width&gt;
          &lt;coplets&gt;
            &lt;coplet id="banknews" number="2" position="1"/&gt;
          &lt;/coplets&gt;
        &lt;/column&gt;
        &lt;column position="3"&gt;
          &lt;width&gt;22%&lt;/width&gt;
          &lt;coplets/&gt;
        &lt;/column&gt;
      &lt;/content&gt;
    &lt;/portal-profile&gt;
    &lt;personal-profile&gt;
      &lt;greeting&gt;Herzlich willkommen&lt;/greeting&gt;
      &lt;messages&gt;
        &lt;coplet_not_available&gt;
          The coplet is currently not available.
        &lt;/coplet_not_available&gt;
      &lt;/messages&gt;
    &lt;/personal-profile&gt;
  &lt;/global-delta&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The User Status Profile</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The user status profile contains often changing information like
            the configuration of configurable coplets, the last login time etc. The user
            status profile is optional, but if it is not accessible, customizable coplets
            are not possible.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For each customizable coplet which is in the portal view of the
            user the status profile contains an XML block with the coplet specific
            configuration for this coplet.</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;status-profile&gt;
    &lt;customization&gt;
      &lt;!-- Custom information for each customizable coplet --&gt;
      &lt;coplet id="popmail" number="3"&gt;
        &lt;host&gt;mail&lt;/host&gt;
        &lt;password&gt;gsgdgsg&lt;/password&gt;
        &lt;mailcount&gt;4&lt;/mailcount&gt;
        &lt;user&gt;walter&lt;/user&gt;
      &lt;/coplet&gt;
    &lt;/customization&gt;
  &lt;/status-profile&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Configuring the portal</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The configuration of the portal is actually a authentication application
          configuration. Please refer to the authentication documentation for more information
          about authentication handler and application configuration.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Inside your authentication handler configuration you define for each portal
          an application configuration for the portal like the example portal called
          "sunBank" below: </font>
  </p>
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>    &lt;application name="sunBank"&gt;
    &lt;configuration name="portal"&gt;
      &lt;!-- This is the portal configuration --&gt;
      &lt;portal-uri&gt;finance-portal&lt;/portal-uri&gt;
      &lt;profile-cache&gt;true&lt;/profile-cache&gt;
      &lt;process-coplets-parallel&gt;false&lt;/process-coplets-parallel&gt;
      &lt;default-coplet-timeout&gt;10000&lt;/default-coplet-timeout&gt;
      &lt;profile&gt;
        &lt;!-- The resource for loading the layout profile --&gt;
        &lt;layout-base uri="cocoon://financeresource-layoutprofile"/&gt;
        &lt;!-- The resource for loading the base coplets profile --&gt;
        &lt;coplet-base uri="cocoon://financeresource-copletprofile"/&gt;
        &lt;!-- The optional resource for saving the base coplets profile --&gt;
        &lt;coplet-base-save uri="cocoon://financeresource-savecopletprofile"/&gt;
        &lt;!-- The optional type resource --&gt;
        &lt;type-base uri="cocoon://financeresource-types"/&gt;
        &lt;!-- The optional type resource for the admin configuration --&gt;
        &lt;admin-type-base uri="cocoon://financeresource-admintypes"/&gt;
        &lt;!-- The resources for loading/saving the deltas --&gt;
        &lt;global-delta-load uri="cocoon://financeresource-globalprofile"/&gt;
        &lt;global-delta-save uri="cocoon://financeresource-saveglobalprofile"/&gt;
        &lt;role-delta-load uri="cocoon://financeresource-roleprofile"/&gt;
        &lt;role-delta-save uri="cocoon://financeresource-saveroleprofile"/&gt;
        &lt;user-delta-load uri="cocoon://financeresource-userprofile"/&gt;
        &lt;user-delta-save uri="cocoon://financeresource-saveuserprofile"/&gt;
        &lt;!-- Optional resources for loading/saving the status profile
                       which is required for persistent, customizable coplets --&gt;
        &lt;user-status-load uri="cocoon://financeresource-loadstatusprofile"/&gt;
        &lt;user-status-save uri="cocoon://financeresource-savestatusprofile"/&gt;
        &lt;!-- optional type resources --&gt;
        &lt;global-type-delta uri="..."/&gt;
        &lt;role-type-delta uri="..."/&gt;
        &lt;user-type-delta uri="..."/&gt;
      &lt;/profile&gt;
      &lt;!-- Redirect to this resource, if the user is not authenticated
                   to view that coplet --&gt;
      &lt;auth-redirect&gt;finance-portal&lt;/auth-redirect&gt;
    &lt;/configuration&gt;
  &lt;/application&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Global Portal Configuration</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">One mandatory configuration value for the portal is the
            <i>portal-uri</i>. It must point to a pipeline which produces the portal view
            for a user (see next section for more information about the pipelines).</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Profile Caching</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The portal contains an intelligent profile caching mechanism which
            detects automatically changes to profiles and determines upon this information
            which profile must be rebuild. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Without profile caching a profile is build each time a user logs
            in. With profile caching the profile is only build if there is no cached
            profile or if something has changed in the profiles for this user. Only the
            user status profile is not cached at all as it is often changing.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">By specifying the <i>profile-cache</i> tag in the the portal
            configuration with the value <i>true</i> the profile caching is turned on. If
            the tag is not available no profile caching is performed.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If profile caching is turned on, the profiles should not be changed
            by hand as the cache does not detect such changes. All changes to the profiles
            must be done using the portal tools. However if you change a profile or part
            of a profile by hand, make sure that you clean the cache afterwords. Cleaning
            the cache can be done either by the provided the portal tools or by deleting all
            files inside the cache directory.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Global coplet configuration</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Usually the portal view is generated step by step, e.g. the coplets
            are build one after the other. The portal can be configured to get the coplets
            content parallel to decrease the response time for the portal view. By
            specifying the <i>process-coplets-parallel</i> tag with the value
            <i>true</i>, the coplets are processed parallel.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the content of a coplet is not available, e.g. if the
            contentresides on an external HTTP server, the processing of this coplet can
            take a "very long" time, e.g. until a timeout occures. The portal monitors the
            coplets and can stop the processing of a coplet after a distinct period of
            time. This period can be specified by the tag "default-coplet-timeout" in
            milliseconds. If the content of the coplet is not available after the time has
            expired, the coplet is declared as "not available". The default timeout is 10
            minutes.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For a fine-tuning of coplet timeouts, each coplet can get its own
            timeout (see the sections below).</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Profile Resources</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each part of the profile has a corresponding resource which is
            invoked for loading or saving the profile part, e.g. one resource for loading
            the global profile delta and a separate one for saving it. The loading
            resources must deliver the xml described in the previous chapters. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">All resources get the parameter "application" with the name of the
            corresponding application and "handler" with the name of the authentication handler.
            The list below shows the additional parameters for the other resources.</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">coplet-base: "profile" with value "coplet-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">coplet-base-save: "profile" with value "coplet-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">layout-base: "profile" with value "layout-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">type-base: "profile" with value "type-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">admin-type-base: "profile" with value "admin-type-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">global-delta-load: "profile" with value "global-delta"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">global-type-delta: "profile" with value "global-type-delta"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">global-delta-save: "profile" with value "global-delta"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">role-delta-load: "profile" with value "role-delta", "role"
               with name of the role
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">role-delta-save: "profile" with value "role-delta", "role"
               with name of the role
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">role-type-delta: "profile" with value "role-type-delta",
               "role" with role name
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-delta-load: "profile" with value "user-delta", "role"
               with role name, "ID" with user ID
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-delta-save: "profile" with value "user-delta", "role"
               with role name, "ID" with user ID
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-type-delta: "profile" with value "user-type-delta",
               "role" with role name, "ID" with user ID
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-status-load: "profile" with value "user-status", "role"
               with role name, "ID" with the user ID
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-status-save: "profile" with value "user-status", "role"
               with role name, "ID" with the user ID
            </font>
  </li>
          
  </ul>
  </blockquote>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">The Pipelines</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">So far the chapters only described configuring the portal and writing
          resources. This chapter closes the gap and explains the steps for showing the
          portal.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For defining the pipelines in the sitemap, the portal declares two
          generators (the "portal" generator and the "portal-conf" generator) and one
          action ("portal-auth").</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Displaying the portal view</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Displaying the portal view is a very simple step: defining a
            pipeline with the "portal" as the generator, the auth-protect action
            for defining the application and an stylesheet for creating the presentation:
            </font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="sunbank-portal"&gt;
    &lt;map:act type="auth-protect"&gt;
      &lt;!-- for getting the portal configuration --&gt;
      &lt;map:parameter name="handler" value="portalhandler"/&gt;
      &lt;map:parameter name="application" value="sunBank"/&gt;
      &lt;map:generate type="portal"/&gt;
      &lt;!-- generate the portal view --&gt;
      &lt;map:transform src="sunbank/styles/portalHTML.xsl"/&gt;
      &lt;!-- presentation in HTML --&gt;
      &lt;map:serialize/&gt;
    &lt;/map:act&gt;
  &lt;/map:match&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The Generated Portal View</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The XML generated by the "portal" generator is not exactly the
               same as for the user profile. The portal optimizes and reorganizes the profile.
               All fields (or nodes) which are changeable have the attributes
               "formdescription", "formpath" and "formtype". "formdescription" is a user
               readable description of the field, "formpath" is the name of the form parameter
               which can be used to set the value and "formtype" indicates the type of the
               field. The belonging type can be found in the types section of the
               profile.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;!-- The portal indicates that the following is the portal view --&gt;
  &lt;portal&gt;
    &lt;!-- The configuration of the portal --&gt;
    &lt;configuration&gt;
      &lt;!-- This is the uri which should be invoked for rebuilding the portal view
               and for changing the view. The parameter portalprofile is always
               present and indicates the current profile. --&gt;
      &lt;uri&gt;finance-portlets?portalprofile=uprofile:sunBank:user_admin_cocoon&lt;/uri&gt;
      &lt;!-- This is the uniquie portal profile ID --&gt;
      &lt;profile&gt;uprofile:sunBank:user_admin_cocoon&lt;/profile&gt;
      &lt;media&gt;html&lt;/media&gt;
      &lt;!-- The current media: html or wap --&gt;
    &lt;/configuration&gt;
    &lt;!-- Now the needed part of the layout profile: --&gt;
    &lt;layout&gt;
      &lt;portal&gt;
        &lt;background&gt;
          &lt;color formdescription="Hintergrundfarbe" formpath="portalconf.0.0" formtype="backgroundcolor"&gt;#aab9bf&lt;/color&gt;
        &lt;/background&gt;
        &lt;font&gt;
          &lt;type&gt;Arial, Helvetica, sans-serif&lt;/type&gt;
          &lt;size&gt;2&lt;/size&gt;
          &lt;color formdescription="Schriftfarbe" formpath="portalconf.1.0" formtype="textcolor"&gt;black&lt;/color&gt;
        &lt;/font&gt;
      &lt;/portal&gt;
      &lt;coplets&gt;
        &lt;title&gt;
          &lt;background&gt;
            &lt;color&gt;#46627A&lt;/color&gt;
          &lt;/background&gt;
          &lt;font&gt;
            &lt;type&gt;Arial&lt;/type&gt;
            &lt;size&gt;2&lt;/size&gt;
            &lt;color&gt;#ffffff&lt;/color&gt;
          &lt;/font&gt;
        &lt;/title&gt;
        &lt;content&gt;
          &lt;background&gt;
            &lt;color&gt;#000000&lt;/color&gt;
          &lt;/background&gt;
          &lt;font&gt;
            &lt;type&gt;Arial&lt;/type&gt;
            &lt;size&gt;2&lt;/size&gt;
            &lt;color&gt;#ffffff&lt;/color&gt;
          &lt;/font&gt;
        &lt;/content&gt;
      &lt;/coplets&gt;
    &lt;/layout&gt;
    &lt;!-- This is the portal view: --&gt;
    &lt;header&gt;
      &lt;coplet id="personalize" position="1" number="1"&gt;
        &lt;resource uri="financecoplet-personalize.xml"/&gt;
        &lt;configuration&gt;
          &lt;mandatory&gt;true&lt;/mandatory&gt;
          &lt;sizable&gt;true&lt;/sizable&gt;
          &lt;active&gt;true&lt;/active&gt;
        &lt;/configuration&gt;
        &lt;title&gt;Personalisieren&lt;/title&gt;
        &lt;status&gt;
          &lt;visible&gt;true&lt;/visible&gt;
          &lt;size&gt;max&lt;/size&gt;
        &lt;/status&gt;
        &lt;content&gt;..the coplet content...&lt;/content&gt;
      &lt;/coplet&gt;
    &lt;/header&gt;
    &lt;columns number="3"&gt;
      &lt;column position="1" width="28%"&gt;
        &lt;coplet id="administration" position="1" number="1"&gt;
          &lt;resource uri="financecoplet-administration.xml"/&gt;
          &lt;configuration&gt;
            &lt;mandatory&gt;false&lt;/mandatory&gt;
            &lt;sizable&gt;true&lt;/sizable&gt;
            &lt;active&gt;true&lt;/active&gt;
          &lt;/configuration&gt;
          &lt;title&gt;Portal Administration&lt;/title&gt;
          &lt;status&gt;
            &lt;visible formdescription="Sichtbar" formpath="portalconf.4.0" formtype="BOOLEAN"&gt;true&lt;/visible&gt;
            &lt;size formdescription="Groesse" formpath="portalconf.5.0" formtype="copletsize"&gt;max&lt;/size&gt;
          &lt;/status&gt;
          &lt;content&gt;..the coplet content...&lt;/content&gt;
        &lt;/coplet&gt;
                          ....
                   &lt;/column&gt;
      &lt;column position="2" width="50%"&gt;
              ...
              &lt;/column&gt;
      &lt;column position="3" width="22%"&gt;
              ...
                   &lt;/column&gt;
    &lt;/columns&gt;
    &lt;!-- The personal information --&gt;
    &lt;personal-profile&gt;
      &lt;greeting&gt;Hi there!&lt;/greeting&gt;
      &lt;messages&gt;
        &lt;coplet_not_available&gt;The coplet is currently not available.&lt;/coplet_not_available&gt;
      &lt;/messages&gt;
    &lt;/personal-profile&gt;
  &lt;/portal&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
        
        
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Administration of the portal view</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Displaying the administration page of the portal is as simple as
            displaying the portal. The difference lies in changing the generator to the
            "portal-conf" generator: </font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="sunbank-conf"&gt;
    &lt;map:act type="auth-protect"&gt;
      &lt;map:parameter name="handler" value="portalhandler"/&gt;
      &lt;map:parameter name="application" value="sunBank"/&gt;
      &lt;map:generate type="portal-conf"/&gt;
      &lt;map:transform src="sunbank/styles/portalconfHTML.xsl"/&gt;
      &lt;map:serialize/&gt;
    &lt;/map:act&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Make sure to protect the portal configuration generator as the
            administrator can change all profiles, clear the cache etc. It should only be
            available for real portal administrators.</font>
  </p>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The Generated Administration View</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The XML generated by the "portal-conf" generator is not exactly
               the same as the user profile. The portal addes some information to the profile.
               All fields (or nodes) which are changeable have the attributes
               "formdescription", "formpath" and "formtype". "formdescription" is a user
               readable description of the field, "formpath" is the name of the form parameter
               which can be used to set the value and "formtype" indicates the type of the
               field. The belonging type can be found in the types section of the
               profile.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;!-- The portalconf node indicates that the following is the portal administration view --&gt;
  &lt;portalconf&gt;
    &lt;!-- The configuration of the portal --&gt;
    &lt;configuration&gt;
      &lt;!-- This is the uri which should be invoked for rebuilding the portal view
               and for changing the view. The parameter portalprofile is always
               present and indicates the current profile. --&gt;
      &lt;uri&gt;finance-portlets?portalprofile=uprofile:sunBank:user_admin_cocoon&lt;/uri&gt;
      &lt;!-- This is the uniquie portal profile ID --&gt;
      &lt;profile&gt;uprofile:sunBank:user_admin_cocoon&lt;/profile&gt;
      &lt;media&gt;html&lt;/media&gt;
      &lt;!-- The current media: html or wap --&gt;
    &lt;/configuration&gt;
    &lt;!-- The layout profile, see chapter about the layout profile --&gt;
    &lt;layout-profile&gt;
      &lt;portal&gt;
        &lt;layouts&gt;
          &lt;layout&gt;
            &lt;background&gt;
              &lt;color formdescription="Hintergrundfarbe" formpath="portalconf.0.0" formtype="backgroundcolor"&gt;#aab9bf&lt;/color&gt;
            &lt;/background&gt;
            &lt;font&gt;
              &lt;type&gt;Arial, Helvetica, sans-serif&lt;/type&gt;
              &lt;size&gt;2&lt;/size&gt;
              &lt;color formdescription="Schriftfarbe" formpath="portalconf.1.0" formtype="textcolor"&gt;black&lt;/color&gt;
            &lt;/font&gt;
          &lt;/layout&gt;
        &lt;/layouts&gt;
        &lt;header&gt;
          &lt;exists&gt;true&lt;/exists&gt;
        &lt;/header&gt;
        &lt;columns&gt;
          &lt;number formdescription="Anzahl" formpath="portalconf.2.0" formtype="columnnumber"&gt;3&lt;/number&gt;
        &lt;/columns&gt;
        &lt;footer&gt;
          &lt;exists&gt;false&lt;/exists&gt;
        &lt;/footer&gt;
      &lt;/portal&gt;
      &lt;coplets&gt;
        &lt;layouts&gt;
          &lt;layout&gt;
            &lt;title&gt;
              &lt;background&gt;
                &lt;color&gt;#46627A&lt;/color&gt;
              &lt;/background&gt;
              &lt;font&gt;
                &lt;type&gt;Arial&lt;/type&gt;
                &lt;size&gt;2&lt;/size&gt;
                &lt;color&gt;#ffffff&lt;/color&gt;
              &lt;/font&gt;
            &lt;/title&gt;
            &lt;content&gt;
              &lt;font&gt;
                &lt;type&gt;Arial&lt;/type&gt;
                &lt;size&gt;2&lt;/size&gt;
                &lt;color&gt;#000000&lt;/color&gt;
              &lt;/font&gt;
              &lt;background&gt;
                &lt;color&gt;#ffffff&lt;/color&gt;
              &lt;/background&gt;
            &lt;/content&gt;
          &lt;/layout&gt;
        &lt;/layouts&gt;
      &lt;/coplets&gt;
    &lt;/layout-profile&gt;
    &lt;!-- The coplets profile, see chapter about the coplets profile --&gt;
    &lt;coplets-profile&gt;
      &lt;coplets&gt;
        &lt;coplet id="banknews"&gt;
          &lt;resource uri="onlinecoplet-banking.xml"/&gt;
          &lt;configuration&gt;
            &lt;mandatory&gt;false&lt;/mandatory&gt;
            &lt;sizable&gt;true&lt;/sizable&gt;
            &lt;active&gt;true&lt;/active&gt;
          &lt;/configuration&gt;
          &lt;title&gt;Banking News&lt;/title&gt;
          &lt;status&gt;
            &lt;visible&gt;true&lt;/visible&gt;
            &lt;size&gt;max&lt;/size&gt;
          &lt;/status&gt;
        &lt;/coplet&gt;
               ...
              &lt;/coplets&gt;
    &lt;/coplets-profile&gt;
    &lt;!-- The type profile, see the chapter about the type profile --&gt;
    &lt;typedefs&gt;
           ...
       &lt;/typedefs&gt;
    &lt;!-- And now the portal view, see chapter about the portal profile --&gt;
    &lt;portal-profile&gt;
      &lt;content&gt;
        &lt;header&gt;
          &lt;coplet id="personalize" position="1" number="1"&gt;
            &lt;status&gt;
              &lt;visible&gt;true&lt;/visible&gt;
              &lt;size&gt;max&lt;/size&gt;
            &lt;/status&gt;
          &lt;/coplet&gt;
        &lt;/header&gt;
        &lt;column position="1"&gt;
          &lt;width formdescription="Breite" formpath="portalconf.3.0" formtype="CARDINAL"&gt;28%&lt;/width&gt;
          &lt;coplets&gt;
            &lt;coplet id="administration" position="1" number="2"&gt;
              &lt;status&gt;
                &lt;visible formdescription="Sichtbar" formpath="portalconf.4.0" formtype="BOOLEAN"&gt;true&lt;/visible&gt;
                &lt;size formdescription="Groesse" formpath="portalconf.5.0" formtype="copletsize"&gt;max&lt;/size&gt;
              &lt;/status&gt;
            &lt;/coplet&gt;
                                 ...
                          &lt;/coplets&gt;
        &lt;/column&gt;
        &lt;column position="2"&gt;
                     ...
                      &lt;/column&gt;
        &lt;column position="3"&gt;
                     ...
                      &lt;/column&gt;
      &lt;/content&gt;
    &lt;/portal-profile&gt;
    &lt;!-- The personal profile, see the corresponding chapter --&gt;
    &lt;personal-profile&gt;
      &lt;greeting&gt;Hi there!&lt;/greeting&gt;
      &lt;messages&gt;
        &lt;coplet_not_available&gt;The coplet is currently not available.&lt;/coplet_not_available&gt;
      &lt;/messages&gt;
    &lt;/personal-profile&gt;
  &lt;/portalconf&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Changing the Profile</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The profile can be changed using a HTTP request. The invoked
            resources is the uri defined in the "configuration" section of the portal view.
            It contains already the needed parameter "portalprofile" with the given value.
            This parameter tells the portal which profile it should change.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"> Each field which is changeable has the parameters
            "formdescription", "formtype" and "formpath". The "formdescription" is a
            user-readable text for this field. The "formtype" is the type of the field. It
            is a type name which has a corresponding entry in the type profile. The type
            profile contains all possible values for this particular type. The "formpath"
            contains the name of the field to change. So changing an field is submitting a
            form value with the name of "formpath" and one of the values denoted by the
            "formtype". </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition to this the portal recognizes the special parameter
            "portalcmd". It can control the appearance of the coplets. The value of the
            parameter is one of the following followed by '_', the coplet id attribute,
            another '_' and the coplet number attribute. For example minimizing a coplet is
            done by passing "portalcmd=minimize_1_3" to the request. The commands are as
            follows:</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">"maximize" : Maximize the coplet.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"minimize" : Minimize the coplet.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"close" or "hide" : Close the coplet, it will not be
               displayed in the portal view, but is still configured.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"open" or "show" : A configured coplet will be included in
               the portal view again.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"delete" : Remove the coplet from the profile.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"move" : Move the coplet to the column which is append to
               value separated by '_'. So "portalcmd=move_1_3_2" would move the coplet into
               the 2nd column.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"new" : Add a new coplet to the profile. Only the attribute
               id of the coplet is passed. Instead of the number attribute the column number
               is appended. If instead "header" or "footer" is passed instead of the column
               number, the coplet is moved into that special area.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"update" : Change from the customization view of the coplet
               to the coplet content view.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The profile can be save persistent by sending the parameter
            "portalcmd" with the value "save"in addition to the "portalprofile"
            parameter.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Defining coplets</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Defining a pipeline for a coplet is also very straightforward.
            Together with your "real" pipeline for defining the content and doing the
            presentation, the "auth-protect" action is needed. This action defines
            the application and portal, the coplet (pipeline) belongs to:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="licence-coplet"&gt;
    &lt;!-- Get the application configuration --&gt;
    &lt;map:act type="auth-protect"&gt;
      &lt;map:parameter name="handler" value="portalhandler"/&gt;
      &lt;map:parameter name="application" value="sunBank"/&gt;
      &lt;!-- secure the coplet: --&gt;
      &lt;map:act type="portal-auth"&gt;
        &lt;map:parameter name="coplet" value="licencing"/&gt;
      &lt;/map:act&gt;
      &lt;!-- The resource containg the licencing information: --&gt;
      &lt;map:generate src="cocoon/licencing.xml"/&gt;
      &lt;!-- present it in HTML --&gt;
      &lt;map:transform src="sunbank/styles/HTML.xsl"/&gt;
      &lt;!-- Serialize it to XML for including in the portal view: --&gt;
      &lt;map:serialize/&gt;
    &lt;/map:act&gt;
  &lt;/map:match&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition you can secure the pipeline of the coplet. So only users
             who can select this coplet in their profile can invoke the pipeline.
             This extra protection is performed by the "portal-auth" action:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="licence-coplet"&gt;
    &lt;!-- Get the application configuration --&gt;
    &lt;map:act type="auth-protect"&gt;
      &lt;map:parameter name="handler" value="portalhandler"/&gt;
      &lt;map:parameter name="application" value="sunBank"/&gt;
      &lt;!-- secure the coplet: --&gt;
      &lt;map:act type="portal-auth"&gt;
        &lt;map:parameter name="coplet" value="licencing"/&gt;
      &lt;/map:act&gt;
      &lt;!-- The resource containg the licencing information: --&gt;
      &lt;map:generate src="cocoon/licencing.xml"/&gt;
      &lt;!-- present it in HTML --&gt;
      &lt;map:transform src="sunbank/styles/HTML.xsl"/&gt;
      &lt;!-- Serialize it to XML for including in the portal view: --&gt;
      &lt;map:serialize/&gt;
    &lt;/map:act&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In this example the coplet is protected by the use of the parameter
            tag inside the "portal-auth" action. Only if the user is allowed to
            view/configure the coplet with the ID "licencing", he can invoke this resource.
            If this security command is left out, everyone is able to get the resource by
            simply invoking it directly from the browser. However, if the coplet is
            protected it is not necessary that a user has choosen that coplet for his
            current portal view to invoke the resource. In addition it is possible to
            specify the parameter without a specific coplet name. This protects the
            resource as a coplet: Only users which are logged in to the portal can view the
            resource.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting Profile Information within a coplet</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each coplet has access to nearly all information of the profile,
            including layout information and configuration. The coplet can retrieve this
            information using a special session context called <i>portal</i>. With the
            familiar commands of the <i>session</i> transformer (<i>getxml</i> etc.)
            the information can be included in the current xml stream of a coplet.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The content of the context looks like the following:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;layout&gt;
    &lt;portal&gt;
      &lt;background&gt;
        &lt;color formdescription="Hintergrundfarbe" formpath="portalconf.0.0" formtype="backgroundcolor"&gt;#aab9bf&lt;/color&gt;
      &lt;/background&gt;
      &lt;font&gt;
        &lt;type&gt;Arial, Helvetica, sans-serif&lt;/type&gt;
        &lt;size&gt;2&lt;/size&gt;
        &lt;color formdescription="Schriftfarbe" formpath="portalconf.1.0" formtype="textcolor"&gt;black&lt;/color&gt;
      &lt;/font&gt;
    &lt;/portal&gt;
    &lt;coplets&gt;
      &lt;title&gt;
        &lt;background&gt;
          &lt;color&gt;#46627A&lt;/color&gt;
        &lt;/background&gt;
        &lt;font&gt;
          &lt;type&gt;Arial&lt;/type&gt;
          &lt;size&gt;2&lt;/size&gt;
          &lt;color&gt;#ffffff&lt;/color&gt;
        &lt;/font&gt;
      &lt;/title&gt;
      &lt;content&gt;
        &lt;background&gt;
          &lt;color&gt;#000000&lt;/color&gt;
        &lt;/background&gt;
        &lt;font&gt;
          &lt;type&gt;Arial&lt;/type&gt;
          &lt;size&gt;2&lt;/size&gt;
          &lt;color&gt;#ffffff&lt;/color&gt;
        &lt;/font&gt;
      &lt;/content&gt;
    &lt;/coplets&gt;
  &lt;/layout&gt;
  &lt;configuration&gt;
    &lt;!-- This is the uri which should be invoked for rebuilding the portal view
               The parameter portalprofile is always
               present and indicates the current profile. --&gt;
    &lt;uri&gt;finance-portlets?portalprofile=uprofile:sunBank:user_admin_cocoon&lt;/uri&gt;
    &lt;!-- This is the uniquie portal profile ID --&gt;
    &lt;profile&gt;uprofile:sunBank:user_admin_cocoon&lt;/profile&gt;
    &lt;media&gt;html&lt;/media&gt;
    &lt;!-- The current media: html or wap --&gt;
  &lt;/configuration&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using this information the coplet can layout itself with the layout
            chosen by the user for the portal. For example a <i>&lt;session:getxml
            context="portal" path="/layout/coplets/content/background/color"/&gt;</i> is
            replaced by the session transformer with the color value for the background
            (here "#000000)".</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Writing Customizable coplets</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Writing a customizable coplet requires two task:</font>
  </p>
          
  <blockquote>
  <ol>
            
  <li>
  <font face="verdana, helvetica, sans serif">Creating the resource for the customization of the coplet
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Creating a resource for the coplet content which uses the
               configuration
            </font>
  </li>
          
  </ol>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The resource for the customization is very similar to the "real"
            resource for the coplet. It is - in most cases - a pipeline which delivers xml
            and this xml is included in the portal view. Usually this xml contains a form
            for the user to define the configuration of the coplet.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The configuration of the coplet is available using the special
            <i>portal</i> session context. For a customizable coplet this context is
            augmented with the current configuration of the coplet:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;layout&gt;
      ...
  &lt;/layout&gt;
  &lt;configuration&gt;
      ...
      &lt;context&gt;unique id for the coplet for external applications&lt;/context&gt;
  &lt;/configuration&gt;
  &lt;coplet-data&gt;
      ... the configuration ....
  &lt;/coplet-data&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the Cocoon form handling it is very easy to write a
            customization view for a coplet. The following example dispalys a form for a
            mail coplet which requires the configuration for a mail host, a user name and a
            password.</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:session="http://cocoon.apache.org/session/1.0"&gt;
    &lt;!-- Define a form --&gt;
    &lt;session:form name="popmail" method="POST"&gt;
      &lt;session:action&gt;
        &lt;!-- The action is send to the pipeline redisplaying the portal --&gt;
        &lt;session:getxml context="portal" path="/configuration/uri"/&gt;
      &lt;/session:action&gt;
      &lt;!-- Create the input fields for
               host, username and password --&gt;
      &lt;session:content&gt;
        &lt;session:inputxml context="portal" path="/coplet-data/host" name="Host" type="text"/&gt;
        &lt;session:inputxml context="portal" path="/coplet-data/user" name="User" type="text"/&gt;
        &lt;session:inputxml context="portal" path="/coplet-data/password" name="Password" type="password"/&gt;
      &lt;/session:content&gt;
      &lt;!-- The submit button --&gt;
      &lt;input type="submit" value="Customize"/&gt;
    &lt;/session:form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>inputxml</i> tags assure that the information
            provided by the user is automatically written into the <i>portal</i> context
            at the places provided.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Writing the resource for the coplet is as easy. The coplet can use
            the <i>getxml</i> command to retrieve to configuration from the
            <i>portal</i> context:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:session="http://cocoon.apache.org/session/1.0"&gt;
    &lt;!-- Get the configuration information out of the portal context --&gt;
    &lt;!-- and feed it into the getmail command --&gt;
    &lt;session:getmail&gt;
      &lt;session:user&gt;
        &lt;!-- Set the user --&gt;
        &lt;session:getxml path="/coplet-data/user" context="portal"/&gt;
      &lt;/session:user&gt;
      &lt;session:password&gt;
        &lt;!-- Set the password --&gt;
        &lt;session:getxml path="/coplet-data/password" context="portal"/&gt;
      &lt;/session:password&gt;
      &lt;session:host&gt;
        &lt;!-- Seet the host --&gt;
        &lt;session:getxml path="/coplet-data/host" context="portal"/&gt;
      &lt;/session:host&gt;
    &lt;/session:getmail&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each time the coplet configuration changes the user status profile
            is automatically saved.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>External Resources and Customizable coplets</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">External resources which are configured with the same authentication
            handler and application as the portal can retrieve configuration information
            from a coplet. If the resource is invoked with the request parameter
            <i>portalcontext</i> it has access to the same portal context as the
            coplet.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The value for the request parameter can be retrieved by the calling
            resource, e.g. the coplet, from the <i>portal</i> context using the path
            <i>/configuration/context</i>. The external resource must have the
            <i>portal-auth</i> action configured in its pipeline. The action
            checks for the request parameter and grants the resource access to the
            <i>portal</i> context of the coplet.</font>
  </p>
       
    
  
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/session.html
  
  Index: session.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>Session Management</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">Session Management</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Dev Guide</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Webapps</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Overview</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Session Contexts</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="authentication.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../howto/xmlform-wizard/howto-xmlform-wizard.html">Form Handling</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="portal.html">Portal</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Scratchpad</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunshine.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunrise.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunspot.html">Portal</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
      
      
    <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Introduction</font>
  <hr style="color: #0086b2" size="1">
      
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i><b>IMPORTANT:</b> This document conforms to the development version of Cocoon. So
          you will only find these components in the current CVS. An early alpha version is already
          available in the latest release of Cocoon, you will find an introduction <a href="sunshine.html">here</a>.
      </i></font></td>
  </tr>
  </table>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A session is a data storage which resides on the server and records
          information about one single user. Cocoon creates a session on demand and
          from that point of time the user is tracked and information can be stored
          inside the session. Each following request of this user is linked to the one
          specific session, so there is always only one session per user on the
          server.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">To avoid a fast growing amount of sessions on the server and the
          overcome potential security problems, a session has usually a valid period of
          time. If during this period no new request comes in from the user, the session
          object on the server will be destroyed by the server (this period of time is
          called session timeout). The web application often allows a user to explictly
          destroy a session.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The usual web applications create sessions during login of a user and
          destroy them when the user logs out.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This document describes the basic Cocoon session management using
          the session transformer.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The chapter "Special Contexts" explains some special
          contexts which do not require a session. They are available everytime. These
          special contexts are the request context, the response context and the
          temporary context.</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Session Tracking</font>
  <hr style="color: #0086b2" size="1">
      
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If a user has a session, Cocoon is able to connect new requests from this user
         to the session of the user. This is done by session tracking. Basically,
         the session tracking of Cocoon uses the session tracking of the environment,
         which is usually the servlet engine.
      </font>
  </p>
      
  <p>
  <font color="black" face="verdana,helvetica,sanserif">There are two methods for session tracking: cookies and url rewriting. If you
         use cookies, you don't have to care about session tracking. Just refer to
         the documentation of your servlet engine on how to turn on cookies for session
         handling.</font>
  </p>
      
  <p>
  <font color="black" face="verdana,helvetica,sanserif">URL rewriting instead is a little bit complicated. For url rewriting, each link
         the user can select, needs a special session ID appended to this link. 
         Unfortunately, this is not done automatically by Cocoon or the servlet engine.
         You can either do this by hand or you can use the <i>encodeURL</i> transformer
         just before the <i>html serializer</i>.
      </font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Sessions</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The session action is responsible for creating and
          terminating a session. It is controlled by a sitemap parameter named "action".
          This parameter can have the values "create" and "terminate". If no parameter is
          set, it defaults to "create".</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The action either creates a new session immediately (if not already
          available), or terminates it (if available).</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Contexts</font>
  <hr style="color: #0086b2" size="1">
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>session Transformer</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The session transformer is responsible for interpreting the tags
            and performing the actions required. The session transformer is configured
            in the sitemap and can be used inside a document. All tags must be prefixed
            with the session namespace. So the actual tag used in the document will read
            <i>&lt;session:xxxx&gt;</i>. The current namespace URI for the session 
            transformer is <i>"http://cocoon.apache.org/session/1.0"</i>.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Context-Tags</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A context is basically an application specific block of XML data in
            the users session. Each context has a unique name.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The command <i>createcontext</i> is used to create a new context.
            A <i>name</i> attribute must be given to the context in order to identify it.
            The following names may not be used: request, response, session,
            context, temp, portal or authentication. If a context of the same name already exists
            then this command will have no effect.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;createcontext name="mycontext"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In order to delete a context the command <i>deletecontext</i> is
            provided. Again a <i>name</i> attribute must be provided.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;deletecontext name="mycontext"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Once created, XML data can then be stored inside or read from a
            given context.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Accessing context data</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The data in a context can be dynamically accessed using the
            following commands.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>getxml</i> allows data to be read out of a context. A
            <i>path</i> attribute describes the source of the data inside the context and
            consists of an XPath expression. All <i>path</i> values must be absolute and
            only nodes and attributes can be accessed. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">An optional default value can also be provided to allow for the
            nonexistence of the requested data.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="mycontext"
            path="/User/Name"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="mycontext"
            path="/User/Name"&gt;Matthew&lt;/getxml&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Attributes can also be accessed.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="mycontext"
            path="/User/Name/@Age"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i></i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Data can be written into a context using the <i>setxml</i>
            command. It is possible to set values or nodes as the following examples
            show.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;setxml context="mycontext"
            path="/User/Name"/&gt;Carsten&lt;/setxml&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;setxml context="mycontext"
            path="/User/"/&gt;&lt;Name&gt;Carsten&lt;/Name&gt;&lt;/setxml&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the <i>setxml</i> command causes all the nodes below the
            target node to be deleted. If you wish to maintain the nodes and manipulate
            individual branches of the XML tree - then the session transformer offers the
            <i>mergexml</i> command.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Use the <i>removexml</i> command to remove nodes from the
            context.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;removexml context="mycontext"
            path="/User/"/&gt;</i></font>
  </p>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Example</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The following example shows the use of several commands and in
               particular how the <i>mergexml</i> command can be used to manipulate context
               data.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;resource xmlns:session="http://cocoon.apache.org/session/1.0"&gt;
    &lt;session:createcontext name="trackdemo"/&gt;
    &lt;!-- build context data --&gt;
    &lt;session:setxml context="trackdemo" path="/"&gt;
      &lt;context&gt;
        &lt;users&gt;
          &lt;user id="1"&gt;
            &lt;name&gt;Carsten&lt;/name&gt;
          &lt;/user&gt;
        &lt;/users&gt;
      &lt;/context&gt;
    &lt;/session:setxml&gt;
    &lt;session:mergexml context="trackdemo" path="/context"&gt;
      &lt;users&gt;
        &lt;user id="1"&gt;
          &lt;name&gt;Ziegeler&lt;/name&gt;
          &lt;developer&gt;true&lt;/developer&gt;
        &lt;/user&gt;
        &lt;user id="2"&gt;
          &lt;name&gt;Walter&lt;/name&gt;
        &lt;/user&gt;
      &lt;/users&gt;
    &lt;/session:mergexml&gt;
    &lt;session:getxml context="trackdemo" path="/"/&gt;
  &lt;/resource&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In the above example, a context for storing data is added. Using
               the <i>setxml</i> command data is then stored into the context. The following
               <i>mergexml</i> command then changes the name of user-1 and adds a further
               tag. As there is no original user-2 the complete subtree is then added to the
               context.</font>
  </p>
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Reading and writing contexts</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Aside from the described means of accessing data in a context,
            the session transformer also provides for the reading and writing of contexts. This can be
            used to write an application context out to a database or to read an
            application context in from a file.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The session transformer offers a very flexible way of defining the source of the
            context data. It is possible to specify a resource (defined in the sitemap) or
            a Java class. Using a resource allows for example the context data to be read
            from a database using the SQL Transformer. As this source is a Cocoon
            pipeline, the data can be generated and transformed before passing into the
            context. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">When a context is created, it can get additional save and load URIs
            which are used for loading/saving to/from the context:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;createcontext name="mycontext" load="cocoon://load-from-db"
            save="cocoon://save-to-db"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">These URIs can then be used inside a document to load data into a
            context:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;loadxml context="mycontext"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This example would then load the context data via the resource
            <i>load-from-db</i> which must be defined in the sitemap.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Parameters can be passed to and interpreted by the uri or the Java
            class. This allows the context data to be read dependent on say the current
            user.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;loadxml
            context="mycontext"&gt;&lt;user&gt;ben&lt;/user&gt;&lt;/loadxml&gt;</i></font>
  </p>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The resource addressed by the uri will receive the parameters as
            request-parameters. In addition the name of the context will always be passed
            as <i>contextname</i>.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Writing context data works in the same manner.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;savexml context="mycontext"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Both commands can use the optional <i>path</i> attribute:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;loadxml context="mycontext" path="/user"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;savexml context="mycotnext" path="/user"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The first command will read xml from the uri and store it in the
            context under the node <i>user</i>, the second one saves only the xml subtree
            under the node <i>user</i> to the uri. The resource addressed by the uri will
            be passed in addition to the <i>contextname</i> parameter the <i>path</i>
            parameter with the corresponding value. If the <i>path</i> attribute is not
            present the <i>path</i> parameter will get the value <i>"/"</i>.</font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Special Contexts</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Cocoon creates and maintains special contexts that allow the
          applications to access the environment data. This allows the read-only access
          to such things as the HttpRequest or the HtppResponse using the same XPath
          commands previously described. These context do not require any session, they
          are everytime available.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Request Context - Accessing the Environment, Part One</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The request context is an XML description of the current
            HttpRequest. This context is a special read only context which can be accessed
            with the usual commands:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="request" path="/parameter"/&gt;</i></font>
  </p>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you for example want to get the value of a parameter with the
            name <i>username</i> you can include the following command in your XML and it
            will be replaced with the value of the parameter:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="request"
            path="/parameter/username"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This command will be replaced with all parameters from the current
            request in XML format. If you wish to obtain the complete querystring as it was
            passed into Cocoon - without converting the data to XML - then you can use
            the "/querystring" path:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="request"
            path="/querystring"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The result will be a string in the format
            "?param=aaa&amp;...".</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The complete context you can access via these commands has the
            following XML format:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;parameter&gt;
    &lt;!-- All parameters: parameter names build the elements with the values as text node childs --&gt;
    &lt;firstparameter&gt;value of parameter&lt;/firstparameter&gt;
    &lt;secondparameter&gt;value of parameter&lt;/secondparameter&gt;
  &lt;/parameter&gt;
  
  &lt;querystring&gt;the querystring with a leading '?' or empty&lt;querystring&gt;
    (The querystring contains only parameters send by the GET method)
  
  &lt;parametervalues&gt;
    &lt;!-- All parameters. The tags are all inside the session namespace.
      The generated xml can be used without modification for the
      session:connection command. --&gt;
    &lt;session:params&gt;
      &lt;session:param&gt;
        &lt;session:name&gt;1st parameter name&lt;/session:name&gt;
        &lt;session:value&gt;1st parameter value&lt;/session:value&gt;
      &lt;/session:param&gt;
               ...
      &lt;session:param&gt;
        &lt;session:name&gt;2nd parameter name&lt;/session:name&gt;
        &lt;session:value&gt;2nd parameter value&lt;/session:value&gt;
      &lt;/session:param&gt;
    &lt;/session:params&gt;
    &lt;!-- If a parameter has more than one value, for each value a
        &lt;session:param&gt; block is generated. --&gt;
  &lt;/parametervalues&gt;
  
  &lt;attributes&gt;
    &lt;!-- lists all attributes, attribute names build the elements
          with the values as text node childs --&gt;
  &lt;/attributes&gt;
  
  &lt;headers&gt;
    &lt;!-- lists all headers, header names build the elements
         with the values as text node childs --&gt;
  &lt;/headers&gt;
  
  &lt;cookies&gt;
    &lt;!-- lists all cookies --&gt;
    &lt;cookie name="..."&gt;
      &lt;value&gt;the cookie value&lt;/value&gt;
      &lt;name&gt;the name of the cookie&lt;/name&gt;
      &lt;comment&gt;value&lt;/comment&gt;
      &lt;domain&gt;value&lt;/domain&gt;
      &lt;path&gt;value&lt;/path&gt;
      &lt;maxAge&gt;value&lt;/maxAge&gt;
      &lt;secure&gt;value&lt;/secure&gt;
      &lt;version&gt;value&lt;/version&gt;
    &lt;/cookie&gt;
  &lt;/cookies&gt;
  
  &lt;characterEncoding&gt;value&lt;/characterEncoding&gt;
  &lt;contentLength&gt;value&lt;/contentLength&gt;
  &lt;contentType&gt;value&lt;/contentType&gt;
  &lt;protocol&gt;value&lt;/protocol&gt;
  &lt;remoteAddress&gt;value&lt;/remoteAddress&gt;
  &lt;remoteHost&gt;value&lt;/remoteHost&gt;
  &lt;scheme&gt;value&lt;/scheme&gt;
  &lt;serverName&gt;value&lt;/serverName&gt;
  &lt;serverPort&gt;value&lt;/serverPort&gt;
  &lt;authType&gt;value&lt;/authType&gt;
  &lt;method&gt;value&lt;/method&gt;
  &lt;contextPath&gt;value&lt;/contextPath&gt;
  &lt;pathInfo&gt;value&lt;/pathInfo&gt;
  &lt;pathTranslated&gt;value&lt;/pathTranslated&gt;
  &lt;remoteUser&gt;value&lt;/remoteUser&gt;
  &lt;requestedSessionId&gt;value&lt;/requestedSessionId&gt;
  &lt;requestURI&gt;value&lt;/requestURI&gt;
  &lt;servletPath&gt;value&lt;/servletPath&gt;
  &lt;isRequestedSessionIdFromCookie&gt;value&lt;/isRequestedSessionIdFromCookie&gt;
  &lt;isRequestedSessionIdFromCookie&gt;value&lt;/isRequestedSessionIdFromCookie&gt;
  &lt;isRequestedSessionIdValid&gt;value&lt;/isRequestedSessionIdValid&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Response Context - Accessing the Environment, Part Two</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The response context is an XML description of the current
            HttpResponse. This context is a special write only context which can be
            accessed with the usual commands:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;session:setxml context="response"
            path="/header"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This command will be removed from the XML and the information will
            be added to the response. Using the response context headers and cookies can be
            added.</font>
  </p>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Adding headers</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Headers can be added either by <i>setxml</i> or by
               <i>appendxml</i>. If <i>setxml</i> is used, the header with the name gets
               the given value, regardless if the header had any value beforehand or not. If
               <i>appendxml</i> is used the value will be added.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;session:setxml context="response" path="/header/headername"&gt;The value&lt;/session:setxml&gt;
  
     or
  
  &lt;session:appendxml context="response" path="/header/headername"&gt;The value&lt;/session:appendxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Adding cookies</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Cookies can be added either by setxml or by appendxml. There is
               no difference between these commands.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;session:setxml context="response" path="/cookie"&gt;
    &lt;!-- Now follows the cookie definition --&gt;
    &lt;name&gt;The cookie name&lt;/name&gt;
    &lt;value&gt;The value of the cookie&lt;/value&gt;
    &lt;!-- The following are optional --&gt;
    &lt;path&gt;value&lt;/path&gt;
    &lt;domain&gt;value&lt;/domain&gt;
    &lt;secure&gt;true or false&lt;/secure&gt;
    &lt;comment&gt;value&lt;/comment&gt;
    &lt;maxAge&gt;value&lt;/maxAge&gt;
    &lt;version&gt;value&lt;/version&gt;
  &lt;/session:setxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Temporary Context</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The temporary context with the name <i>"temp"</i> is available on
            each request. It is independent from the session and has no content when a new
            request starts. It can be used like any other context except that the content
            is lost when the current response is finished.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the tempory context it is possible to use store any xml
            information for processing the current request.</font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Form Handling</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">To get feedback or information from a user, forms are commonly used
          to present input field in the browser. The usual approach for form handling in
          web application consists of two steps. The first request presents the form to
          the user. This form initiates a second request that processes the form
          values.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Cocoon supports this two step process, in addition Cocoon offers
          a single step approach.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The common approach</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The common approach consists of two steps or of creating two
            resources. The first resource defines the form: All input fields are declared,
            each gets a unique name. This form invokes the second resource.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This resource uses the session transformer to get the values
            provided by the user. The values are added by the browser to the parameters of
            the request. So using the request context and <i>getxml</i>, the values can
            be fetched.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you want to create a form with two values - forename and surname
            of the user, you could generate a base xml file with the information about this
            form:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page&gt;
    &lt;form&gt;
      &lt;action&gt;form-handling-page&lt;/action&gt;
      &lt;input name="forename" type="text"/&gt;
      &lt;input name="surname" type="text"/&gt;
    &lt;/form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A stylesheet can transform this into valid html. The action tag
            indicates that the "form-handling-page" should be invoked by submitting the
            values.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The "form-handling-page" is a pipeline which is declared in the
            sitemap and uses the session transformer. It could also read the following
            xml:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:session="http://cocoon.apache.org/session/1.0"&gt;
    &lt;forename&gt;
      &lt;session:getxml context="request" path="/parameter/forename"/&gt;
    &lt;/forename&gt;
    &lt;surname&gt;
      &lt;session:getxml context="request" path="/parameter/surname"/&gt;
    &lt;/surname&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">As the form values are appended to the request, <i>getxml</i>
            with specifying the path (which is the parameter name used for the input field)
            inserts the value submitted by the user into the xml stream.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you want to write the information in a session context, you must
            wrap the whole xml inside a setxml:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:session="http://cocoon.apache.org/session/1.0"&gt;
    &lt;session:setxml context="userdata" path="/user"&gt;
      &lt;forename&gt;
        &lt;session:getxml context="request" path="/parameter/forename"/&gt;
      &lt;/forename&gt;
      &lt;surname&gt;
        &lt;session:getxml context="request" path="/parameter/surname"/&gt;
      &lt;/surname&gt;
    &lt;/session:setxml&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The user data is now stored inside the session context "userdata",
            so the context has the following content:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;user&gt;
    &lt;forename&gt;Walter&lt;/forename&gt;
    &lt;surname&gt;Walterson&lt;/surname&gt;
  &lt;/user&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Session Framework approach</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The previous chapter showed the common approach for handling form
            values. It forces the user to create two resources for a single form
            handling.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Cocoon offers an advanced approach. Only one single resource is
            created. This resources contains the information about the input fields used
            and in addition the information about where the submitted values should be
            stored inside the session.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The example from the previous chapter could look like this:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:session="http://cocoon.apache.org/session/1.0"&gt;
    &lt;session:form name="myform"&gt;
      &lt;session:action&gt;the-next-page&lt;/session:action&gt;
      &lt;session:content&gt;
        &lt;session:inputxml name="forename" type="text" context="userdata" path="/user/forename"/&gt;
        &lt;session:inputxml name="surname" type="text" context="userdata" path="/user/surname"/&gt;
      &lt;/session:content&gt;
    &lt;/session:form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The form tag starts the form definition. The name attribute is
            required to distinct between different forms on the same page. The action tag
            defines the url invoked by the form and the content tag describes the content
            of the form: its input fields.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>inputxml</i> tag tells Cocoon that the following request
            contains form values which should be stored in the specified context under the
            given path. The session transformer transforms by removing the namespace and
            the context attribute:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:session="http://cocoon.apache.org/session/1.0"&gt;
    &lt;form action="the-next-page"&gt;
      &lt;inputxml name="forename" type="text"/&gt;
      &lt;inputxml name="surname" type="text"/&gt;
    &lt;/form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A stylesheet can now generate the appropriate html (or any other
            format). The main difference is, that the resource invoked by submitting the
            values has not to care about the form as Cocoon maintains the form handling.
            The only prerequisit is that a session for the current user and a session
            context to store the information exists.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The Cocoon approach allows a very easy way of form handling where
            the resource which creates the form also handles the form.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For editing values - if the context already contains information
            about the user - <i>inputxml</i> inserts the current value inside the tag. So
            the xml streamed would after a second run would look like this:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:session="http://cocoon.apache.org/session/1.0"&gt;
    &lt;form action="the-next-page"&gt;
      &lt;inputxml name="forename" type="text"&gt;Walter&lt;/inputxml&gt;
      &lt;inputxml name="surname" type="text"&gt;Walterson&lt;/inputxml&gt;
    &lt;/form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Like <i>getxml</i> it is also possible to provide default values
            for the input field, if the context does not contain any information:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;session:inputxml name="forename" context="userdata" path="/user/forename"&gt;
       Defaultname
  &lt;/session:inputxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
    
  
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/sunrise.html
  
  Index: sunrise.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>sunRise Documentation</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">sunRise Documentation</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Dev Guide</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Webapps</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Overview</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="authentication.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../howto/xmlform-wizard/howto-xmlform-wizard.html">Form Handling</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="portal.html">Portal</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Scratchpad</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunshine.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Authentication</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunspot.html">Portal</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
      
      
    <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Introduction</font>
  <hr style="color: #0086b2" size="1">
      
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i><b>IMPORTANT:</b> sunRise (= authentication framework) is part of the scratchpad area 
         of the current Cocoon
         release. This means it is not officially released yet. The API and functionality might change
          before it is moved into the official release. Using this is at your own risk!
          If you want to catch the latest status of these components check out Cocoon 
          from CVS and have a look at this <a href="authentication.html">upto-date documentation</a>.
      </i></font></td>
  </tr>
  </table>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The central point for building a web application is sunRise. It is a
          flexible module for authentication and user management. A user can be
          legitimated using any information available via any source, e.g. a database or
          LDAP. With this mechanism it is very easy and fast to use an exisiting user
          management/authentication system.</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Sitemap-Components</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunRise adds some actions to the sitemap: the <i>sunRise-auth</i>
          action, the <i>sunRise-login</i> action, the <i>sunRise-logout</i> action
          and the <i>sunRise-loggedIn</i> action. The <i>sunRise-auth</i> action gets
          the configuration for sunRise and controlles the pipelines. The
          <i>sunRise-login</i> and the <i>sunRise-logout</i> action control the
          authentication the <i>sunRiseLoggedIn</i> action controlles the application
          flow.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The use of sunRise and its components is described in the following
          chapters.</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">User Authentication</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">One feature of sunRise is the user authentication. A resource can be
          accessible for everyone or it can be protected using sunRise. The process of
          requesting a resource can be described as follows:</font>
  </p>
       
  <blockquote>
  <ol>
          
  <li>
  <font face="verdana, helvetica, sans serif">The user request a resource (original resource).
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">sunRise checks if this resource is protected. If no protection
            is specified, the response to the request is this original resource.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">The resource is protected and sunRise checks, if the user is
            authenticated to view it.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">If the user is authenticated, the response is the original
            resource. If not sunRise redirects to a special redirect-to resource. This
            redirect-to resource is freely configurable and can for example contain
            information about the unauthorized access and in addition a login form.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">Using the login form an authentication resource can be called
            with the corresponding user information (e.g. user id and password). This
            authentication resource uses sunRise for the authentication process.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">In case of a successful authentication sunRise can redirect to
            the original resource (or to any configured start resource).
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">If the authentication failed another resource is invoked by
            sunRise displaying information to the user.
          </font>
  </li>
       
  </ol>
  </blockquote>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This process is only one example for a use-case of sunRise. sunRise
          can be configured for any authentication scheme. All resources are freely
          configurable.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The sunRise handler</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The basic object for authentication in sunRise is the sunRise
            handler. It controlles the access to the resources. Each resource in the
            sitemap can be related to exactly one sunRise handler. All resources belonging
            to the same handler are protected in the same way. If a user has access to the
            handler, the user has the same access rights for all resouces of this
            handler.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each sunRise handler needs the following mandatory
            configuration:</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">A unique name.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The authentication resource which does the real
               authentication.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The redirect-to resource where sunRise redirects to for any
               unauthorized request.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using a unique name for each handler (only alphabetical characters
            and digits are allowed for the handler name), sunRise manages different
            handlers. So various parts of the sitemap can be protected in different ways. A
            resource can be protected by calling this handler using the sunRise-auth
            action. The "sunRise-auth" action must be included in the pipeline of the
            resource. It gets the handler information as a parameter:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>    &lt;map:match pattern="protectedresource"&gt;
          &lt;map:act type="sunRise-auth"&gt;
              &lt;map:parameter name="handler" value="unique handler name"/&gt;
  
              &lt;map:generate src="source/resource.xml"/&gt;
          &lt;/map:act&gt;
          ...
      &lt;/map:match&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the pipeline does not use the "sunRise-auth" action or the
            parameter "handler" is missing, the resource is accessible by any user.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The redirect-to resource</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the requested resource is not accessible for the user, sunRise
            redirects to a special redirect-to resource. This resource is a mandatory
            configuration of the sunRise handler:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;action name="sunRise-auth" ...&gt;
      &lt;handlers&gt;  &lt;!-- Now follows the handlers configuration --&gt;
          &lt;handler name="unique"&gt;
              &lt;redirect-to uri="cocoon://loginpage"/&gt; &lt;!-- The login resource --&gt;
          &lt;/handler&gt;
      &lt;/handlers&gt;
  &lt;/action&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This redirect-to resource is an unprotected resource in the
            sitemap. For tracking which resource was requested, the redirect-to resource
            gets the request parameter "resource" with the value. In addition all
            parameters specified inside the <i>redirect-to</i> tag of the handler
            configuration are passed to the resource.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This redirect-to resource can contain a form for the user
            authentication. This form should invoke the real login resource which is
            described below.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The authentication process is done by the "sunRise-login" action.
            The login resource contains this action: </font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>	&lt;map:match pattern="login"&gt;
       &lt;map:act type="sunRise-login"&gt;
              &lt;map:parameter name="handler" value="unique"/&gt;
                &lt;map:parameter name="parameter_userid" value="request:name"/&gt;
                &lt;map:parameter name="parameter_password" value="request:password"/&gt;
  
         &lt;map:redirect-to uri="authentication-successful"/&gt;
          &lt;/map:act&gt;
       &lt;!-- authentication failed: --&gt;
             &lt;map:generate src="auth_failed.xml"/&gt;
          &lt;map:transform src="tohtml.xsl"/&gt;
          &lt;map:serialize/&gt;
      &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The "sunRise-auth" action uses the handler parameter to call the
            authentication resource of this handler. This authentication resource needs to
            know the information provided by the user. For each piece of information an own
            parameter is created which name starts with "parameter_". So in the example
            above, the authentication resource gets two parameters: userid and password. As
            the values for these parameters were send by a form they need to be passed on
            to the authentication resource. If you use "request:..." for the value of a
            parameter, the sunRise-login action will pass the actual value of that request
            parameter to the authentication resource.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the user is not authenticated with this handler, sunRise calls
            the authentication resource and passes it the parameters. If this
            authentication is successful, the action returns an empty map and the sitemap
            commands inside the map:act are executed. If the authentication fails, these
            are skipped.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the authentication is successful, a session object is created on
            the server (if not already done). </font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The authentication resource</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The last chapters described the authentication process but left out
            details about the authentication itself. This chapter closes this gap.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The authentication can be done by different components:</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">A sitemap resource.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">A distant resource, e.g. requested via HTTP.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">A java class.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using this flexible approach nearly any kind of authentication is
            possible (e.g. database, LDAP). The authentication resource is another
            mandatory configuration of the sunRise handler:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;action name="sunRise" ...&gt;
      &lt;handlers&gt;  &lt;!-- Now follows the handlers configuration --&gt;
          &lt;handler name="unique"&gt;
              &lt;redirect-to uri="cocoon:raw://loginpage"/&gt; &lt;!-- The login resource --&gt;
              &lt;authentication uri="cocoon:raw://authenticationresource"/&gt;
          &lt;/handler&gt;
      &lt;/handlers&gt;
  &lt;/action&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the authentication resource is a sitemap resource or a remote
            resource, this resource is requested by sunRise with the given parameters from
            the <i>sunRise-login</i> action (see previous chapter: parameters: userid and
            password). In addition all parameters inside the <i>authentication</i> tag of
            the handler configuration are passed to the resource. The response for this
            resource must contain valid XML conforming to the following scheme:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;authentication&gt;
      &lt;ID&gt;value&lt;/ID&gt;
      &lt;role&gt;rolename&lt;/role&gt; &lt;!-- optional --&gt;
      &lt;data&gt;
          ... resource specific data for the user
      &lt;/data&gt;
  &lt;/authentication&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunRise checks the response of the authentication resource for the
            given scheme: the root node must be named "authentication" and one child called
            "ID" must be present. In this case the authentication is successfull and
            sunRise creates a sunRise session context and stores the XML inside. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The mandatory information inside this XML scheme, the "ID" tag, is
            an unique identification for the given user inside the web application. The
            "role" is optional and can for example be used for categorizing users and
            displaying different functionality inside sunSpot (the sunShine portal
            engine).</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the "data" node the authentication resource can pass any
            information of the user into the session object.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the authentication is not successful, the resource must create
            an XML with the root node "authentication". In addition a "data" node can be
            added containing more information about the unsuccessful attempt. This data
            node is then added inside the "login" tag of the login resource (see previous
            chapter).</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Logging out</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The logout process is triggered by the "sunRise-logout"
            action:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:act type="sunRise-logout"&gt;
      &lt;map:parameter name="handler" value="unique"/&gt;
  &lt;/map:act&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This action logs the user out of the given handler and removes all
            information about this handler stored in the session.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Working With subsitemaps</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The common solution for sunRise and subsitemaps is to define the
            handler (and therefore the sunRise action) in the main sitemap. The resources
            in the subsitemap are then simply protected in the same way as if the action
            were declared in the main sitemap. This makes moving resources from one sitemap
            to the other very simple.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><b>However, there is one drawback with this solution. After
            you have started your server, make sure that first a resource using sunRise
            from the main sitemap is invoked, before any of the subsitemap!</b></font>
  </p>
  
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">User Management</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition to the authentication sunRise manages all kinds of
          information belonging to the user in XML format. For this reason sunRise
          creates an own session context called sunRise. All information is stored in
          this context.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The authentication information (the "authentication" scheme retrieved
          from the authentication resource) is stored in this context, so you can
          retrieve and change the information using the sunShine transformer and the
          usual getxml, setxml etc. commands, so we suggest you to read the sunShine
          context document.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting information from the context</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each information from within the context is gettable using an XML
            tag:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;sunshine:getxml context="sunRise" path="/authentication/ID"/&gt; &lt;!-- Get the ID --&gt;
  &lt;sunshine:getxml context="sunRise" path="/authentication/data/username"/&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The path expression is an absolute XPath-like expression where only
            concrete nodes and attributes are allowed. The sunShine transformer replaced
            the tag with the value of the first node found in the context, this can either
            be text or XML.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Setting information in the context</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using another tag information can be stored into the
            context:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;sunshine:setxml context="sunRise" path="/authentication/data/usersername"&gt;
      Mr. Sunshine
  &lt;/sunshine:setxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Again the path is an absolute XPath-like expression where only
            concrete nodes and attributes are allowed. If the requested node exists,
            sunRise changes the value of that node. If the node does not exists, sunRise
            adds it to the context with the given value.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The tag is removed from the resource.</font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Application Management</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A very useful feature for building and maintaining web applications
          is the application management of sunRise. It allows to configure different
          applications and to manage the user data for these applications.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Configuring an Application</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A "sunRise" application is related to one sunRise handler, so an
            application is part of the sunRise handler configuration:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;action name="sunRise" ...&gt;
      &lt;handlers&gt;
          &lt;handler name="unique"&gt;
               ....redirect-to/authentication configuration
               &lt;applications&gt; &lt;!-- the applications for this handler --&gt;
                   &lt;application name="unique"&gt;
                       &lt;load uri="loadapp"/&gt; &lt;!-- optional --&gt;
                       &lt;save uri="saveapp"/&gt; &lt;!-- optional --&gt;
                   &lt;/application&gt;
               &lt;/applications&gt;
          &lt;/handler&gt;
      &lt;/handlers&gt;
  &lt;/action&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A configuration for an application consists of a unique name (only
            alphabetical characters and digits are allowed for the application name) and
            optional load and save resources. The application configuration can contain
            application specific configuration values for the various parts of the
            application, e.g. information for a portal.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">On a successful authentication sunRise invokes for each application
            of the handler the load resource (if present). The content or result of the
            load resource is stored into the session context.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The user does not always visit all sides or all applications at
            once. So it is not necessary to load all applications in advance when not all
            information is needed. Each application can specify if the data is loaded on
            successful authentication or the first time needed:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>....&lt;application name="unique" loadondemand="true"/&gt;...</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The load resource gets several parameters: all values of the
            subnodes of the "authentication" node from the sunRise context (e.g. ID, role
            etc.) and the parameter "application" with the unique name of the application.
            This unique name must not contain one of the characters '_', ':' or '/'.</font>
  </p>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition the load and save resource get all parameters specified
            inside the load / save tag of the handler configuration.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Configuring the resources</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For managing the application sunRise needs to know to which
            application a resource belongs. So in addition to the handler parameter the
            sunRise action gets the application name as a second parameter:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>    &lt;map:match pattern="protectedresource"&gt;
          &lt;map:action type="sunRise-auth"&gt;
              &lt;map:parameter name="handler" value="unique handler name"/&gt;
              &lt;map:parameter name="application" value="unique application name"/&gt;
  
              &lt;map:generate src="source/resource.xml"/&gt;
              ...
          &lt;/map:action&gt;
      &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">With this mechanism each application resource can easily access its
            and only its information. If a resource has no "application" parameter it can
            not access information of any application.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting, setting and saving application information</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Analogue to the access of the authentication data a resource can
            access its application data:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;sunshine:getxml context="sunRise" path="/application/username"/&gt;
  &lt;sunshine:setxml context="sunRise"  path="/application/shoppingcart"&gt;&lt;item1/&gt;&lt;item2/&gt;&lt;/sunRise:setxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The path underlies the same restrictions and rules as always, but
            it has to start with "/application/". </font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Module Management</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition to the application management sunRise offers a facility
          called module management. It enhances the application management by the
          possibility to configure components for the application. For example sunSpot is
          the sunShine portal engine. It needs information about where the portal profile
          for the user is retrieved from, where the layout is stored etc. Now each portal
          needs this information. Assuming that a portal is an application each
          application needs this sunSpot information. As only sunSpot itself knows what
          information it needs, the module management is a standarized way for
          configuring such components.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The module configuration is part of the application
          configuration:</font>
  </p>
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;action name="sunRise" ...&gt;
      &lt;handlers&gt;
          &lt;handler name="unique"&gt;
               ....redirect-to/authentication configuration
               &lt;applications&gt; &lt;!-- the applications for this handler --&gt;
                   &lt;application name="unique"&gt;
                       ...
                       &lt;configuration name="sunSpot"&gt;
                             ...sunSpot configuration
                       &lt;/configuration&gt;
                   &lt;/application&gt;
               &lt;/applications&gt;
          &lt;/handler&gt;
      &lt;/handlers&gt;
  &lt;/action&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">So whenever the module sunSpot is asked to build the portal it can
          easily retrieve its configuration from the current application by getting the
          module configuration named "sunSpot".</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">sunRise User Administration</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using sunRise it is possible to add new roles to the system and to
          add new users. For this purpose, there are several optional entries for the
          sunRise handler which provide the needed functionality:</font>
  </p>
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;action name="sunRise" ...&gt;
      &lt;handlers&gt;
          &lt;handler name="unique"&gt;
               ...redirect-to/authentication configuration...
  
               &lt;!-- Optional resource for loading user information --&gt;
                           &lt;load-users uri="cocoon:raw://financeresource-sunrise-loaduser"/&gt;
  
               &lt;!-- Optional resource for loading roles information--&gt;
                           &lt;load-roles uri="cocoon:raw://financeresource-sunrise-roles"/&gt;
  
               &lt;!-- Optional resource for creating a new user --&gt;
                           &lt;new-user uri="cocoon:raw://financeresource-sunrise-newuser"/&gt;
  
               &lt;!-- Optional resource for creating a new role --&gt;
                           &lt;new-role uri="cocoon:raw://financeresource-sunrise-newrole"/&gt;
  
               &lt;!-- Optional resource for changing user information --&gt;
                           &lt;change-user uri="cocoon:raw://financeresource-sunrise-newuser"/&gt;
  
               &lt;!-- Optional resource for deleting a role --&gt;
                           &lt;delete-role uri="cocoon:raw://financeresource-sunrise-delrole"/&gt;
  
               &lt;!-- Optional resource for deleting a user--&gt;
                           &lt;delete-user uri="cocoon:raw://financeresource-sunrise-deluser"/&gt;
          &lt;/handler&gt;
      &lt;/handlers&gt;
  &lt;/action&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The entries are described in the following subchapters. All tags can
          have additional parameter definitions which are passed to the given resource,
          e.g:</font>
  </p>
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;!-- Optional resource for deleting a user--&gt;
  &lt;delete-user uri="cocoon:raw://financeresource-sunrise-deluser"&gt;
        &lt;connection&gt;database&lt;/connection&gt;
        &lt;url&gt;db:usertable&lt;/url&gt;
  &lt;/delete-user&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting Roles</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>load-roles</i> resource is invoked from sunRise whenever
            it needs information about the available roles. This resource gets the
            parameter "type" with the value "roles" and should deliver an XML schema with
            the root node "roles" and for each role a subelement "role" with a text child
            of the rolename:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;roles&gt;
      &lt;role&gt;admin&lt;/role&gt;
      &lt;role&gt;guest&lt;/role&gt;
      &lt;role&gt;user&lt;/role&gt;
  &lt;/roles&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting Users</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>load-users</i> resource is called whenever information
            about the available users is needed. There are three different uses of this
            resource:</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">Loading all users: The resource gets the parameter "type"
               with the value "users". It should then deliver all users in the system.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Loading all users of one role. The resource gets the
               parameters "type" with the value "users" and "role" with the rolename.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Load information of one user. The resource gets the
               parameters "type" with the value "user", "role" with the rolename and "ID" with
               the sunRise ID of the user.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The XML format of the resource should look like the
            following:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;users&gt;
      &lt;user&gt;
          &lt;ID&gt;sunRise ID&lt;/ID&gt;
          &lt;role&gt;rolename&lt;/role&gt;
          &lt;data&gt; ... application specific data ... &lt;/data&gt;
      &lt;/user&gt;
      &lt;user&gt;
           ...
      &lt;/user&gt;
      ...
  &lt;/users&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Creating a new role</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>new-role</i> resource creates a new role in the system. It
            gets the parameters "type" with the value "role" and "role" with the new
            rolename.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Creating a new user</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>new-user</i> resource creates a new user with a role. It
            gets the parameters <i>"type"</i> with the value <i>"user"</i>,
            <i>"role"</i> with the rolename and <i>"ID"</i> with the new ID for this
            user.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The sunrise transformer offers a tag to create a newuser:
            <i>"adduser"</i>. The input for this element is all information needed to add
            a user including the ID and the role. All these values are then passed on to
            the <i>"new-user"</i> resource:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;adduser&gt;
      &lt;ID&gt;New ID for this user&lt;/ID&gt;
      &lt;role&gt;The role&lt;/role&gt;
      &lt;!-- and now application specific information in the following form:
           &lt;name_of_the_information&gt;value&lt;/name_of_the_information&gt;
      --&gt;
      &lt;firstname&gt;x&lt;/firstname&gt;
      &lt;lastname&gt;y&lt;/lastname&gt;
      ...
  &lt;/adduser&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In the example above a sunRise tries to create a new user with the
            given <i>"ID"</i> and <i>"role"</i>. The <i>"new-user"</i> resource gets
            also the parameters <i>"firstname"</i> and <i>"lastname"</i> with the
            values <i>"X"</i> and <i>"Y"</i>.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If no user with this ID exists the "sunrise:adduser" element is
            replaced with the element "success". Inside this element all the values are
            repeated inside the "values" element:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;success&gt;
      &lt;values&gt;
          &lt;ID&gt;New ID for this user&lt;/ID&gt;
          &lt;role&gt;The role&lt;/role&gt;
          &lt;firstname&gt;x&lt;/firstname&gt;
          &lt;lastname&gt;y&lt;/lastname&gt;
      &lt;/values&gt;
  &lt;/success&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If a user already exists with this ID the response looks like
            this:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;error&gt;
      &lt;id-exists/&gt;
      &lt;values&gt;
          &lt;ID&gt;New ID for this user&lt;/ID&gt;
          &lt;role&gt;The role&lt;/role&gt;
          &lt;firstname&gt;x&lt;/firstname&gt;
          &lt;lastname&gt;y&lt;/lastname&gt;
      &lt;/values&gt;
  &lt;/error&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If an error occurs the response is this:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;error&gt;
      &lt;exception/&gt;
      &lt;values&gt;
          &lt;ID&gt;New ID for this user&lt;/ID&gt;
          &lt;role&gt;The role&lt;/role&gt;
          &lt;firstname&gt;x&lt;/firstname&gt;
          &lt;lastname&gt;y&lt;/lastname&gt;
      &lt;/values&gt;
  &lt;/error&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Changing information of a user</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>change-user</i> resources changes information of a user.
            It gets the parameters "type" with the value "user", "role" with the rolename
            and "ID" with the ID of the user. In addition all - application specific -
            information of this user is send as parameters.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Delete a user</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>delete-user</i> resource should delete a user. It gets the
            parameters "type" with the value "user", "role" with the rolename and "ID" with
            the ID of the user.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Delete a role</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>delete-role</i> resources deletes a role. It gets the
            parameters "type" with the value "role" and "role" with the rolename .</font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">sunRise Configuration Summary</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Here is a brief summary of the sunRise handler configuration: </font>
  </p>
  
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;action name="sunRise" ...&gt;
      &lt;handlers&gt;
          &lt;handler name="unique"&gt;
               &lt;redirect-to uri="cocoon:raw://loginpage"/&gt; &lt;!-- The redirect-to resource --&gt;
  
               &lt;!-- Authentication resource --&gt;
               &lt;authentication uri="cocoon:raw://authenticationresource"&gt;
                   &lt;!-- optional parameters --&gt;
               &lt;/load&gt;
               &lt;!-- optional save resource --&gt;
               &lt;save uri="cocoon:raw://authenticationsaveresource"&gt;
                   &lt;!-- optional parameters --&gt;
               &lt;/save&gt;
  
               &lt;applications&gt; &lt;!-- the applications for this handler --&gt;
                   &lt;application name="unique"&gt;
  
                       &lt;!-- Loading/Saving --&gt;
                       &lt;load uri="cocoon:raw://loadapp"&gt; &lt;!-- optional --&gt;
                          &lt;!-- optional parameters --&gt;
                       &lt;/load&gt;
                       &lt;save uri="cocoon:raw://saveapp"&gt; &lt;!-- optional --&gt;
                           &lt;!-- optional parameters --&gt;
                       &lt;/save&gt;
  
                                                  &lt;!-- module configurations: --&gt;
                       &lt;configuration name="sunSpot"&gt;
                             ...sunSpot configuration
                       &lt;/configuration&gt;
                   &lt;/application&gt;
  
               &lt;/applications&gt;
          &lt;/handler&gt;
      &lt;/handlers&gt;
  &lt;/action&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Pipeline Patterns</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">As explained in the previous chapters, sunRise uses the sunRise
          action for authentication and protecting resources. This chapter shows some
          common used patterns of the pipelines for using sunRise.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Single protected resource</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For protecting a resource with a sunRise handler only the sunRise
            action with the parameter configuration for the handler is required.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Pattern:</font>
  </p>
          
  <blockquote>
  <ol>
            
  <li>
  <font face="verdana, helvetica, sans serif">Pipeline matching
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Using the sunRise-auth action for protecting
            </font>
  </li>
          
  </ol>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Example:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="protected"&gt;
      &lt;map:act type="sunRise-auth"&gt;  &lt;!-- protect the resource --&gt;
          &lt;map:parameter name="handler" value="myhandler"/&gt;
  
          &lt;map:generate src="resource.xml"/&gt;
          &lt;map:transform src="toHTML"/&gt;
          &lt;map:serialize/&gt;
      &lt;/map:act&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">It is very important that the sunRise action wrapps the real
            pipeline, as the pipeline is only invoked if the action grants access. The
            matching must be done before the action is checked as the action performs a
            redirect for this resource.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Multiple protected resources</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Often you want to protect a bunch of resources in the same way. One
            solution is to use the single protected resource pattern for each resource.
            With the multiple protected resource pattern you only have to use the action
            once for all resources and not within each resource.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The prerequisite for this is a common pattern for the
            resources:</font>
  </p>
          
  <blockquote>
  <ol>
            
  <li>
  <font face="verdana, helvetica, sans serif">Pipeline pattern matching
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Using the sunRise action for protection
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Pipeline matching
            </font>
  </li>
          
  </ol>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Example:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="protected-*"&gt;
  
      &lt;map:act type="sunRise-auth"&gt;  &lt;!-- protect the resource --&gt;
          &lt;map:parameter name="handler" value="myhandler"/&gt;
  
          &lt;map:match pattern="protected-first"&gt;
              &lt;map:generate src="resource1.xml"/&gt;
              &lt;map:transform src="toHTML"/&gt;
              &lt;map:serialize/&gt;
          &lt;/map:match&gt;
          ....
          &lt;map:match pattern="protected-second"&gt;
              &lt;map:generate src="resource2.xml"/&gt;
              &lt;map:transform src="toHTML"/&gt;
              &lt;map:serialize/&gt;
          &lt;/map:match&gt;
  
      &lt;/map:act&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Very important - as explained with the single resource pattern - is
            the leading match before the action is performed. The second match is required
            to check which pipeline to use.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Controlling the Application Flow</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you want to create resources which behave different wheather you
            are logged in or not, the <i>sunRiseLoggedIn</i> action is the component to
            controll your application flow. This action checks if the user is authenticated
            for a given handler and calls all sitemap components inside the <i>act</i>
            tag.</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern="startpage"&gt;
  
      &lt;map:act type="sunRise-loggedIn"&gt;  &lt;!-- check authentication --&gt;
          &lt;map:parameter name="handler" value="myhandler"/&gt;
  
          &lt;map:redirect-to uri="loggedInStartPage"/&gt;
      &lt;/map:act&gt;
  
      &lt;map:generate src="startpage.xml"/&gt;
      &lt;map:transform src="toHTML"/&gt;
      &lt;map:serialize/&gt;
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In the example above, if the user is already logged he is
            redirected to the <i>loggedInStartPage</i> resource. If he is not logged in
            for the given handler, the usual start page is generated.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Both actions, the <i>sunRise-auth</i> and the
            <i>sunRise-loggedIn</i> action return - if the user is logged in for the
            given handler - all values from the context to the sitemap, e.g. ID, role etc.
            These values can be used within the other components:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern"protected"&gt;
      &lt;map:act type="sunRise-auth"&gt;  &lt;!-- protect the resource --&gt;
          &lt;map:parameter name="handler" value="myhandler"/&gt;
  
          &lt;!-- Append the ID of the user to the file name --&gt;
          &lt;map:generate src="resource_{ID}.xml"/&gt;
          &lt;map:transform src="toHTML"/&gt;
          &lt;map:serialize/&gt;
  
      &lt;/map:act&gt;
  
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">But the sunRise-loggedIn action does not give the included pipeline
            access to the sunRise context belonging to the handler. If you want this, you
            have to nest the sunRise action inside!</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;map:match pattern"start"&gt;
  
      &lt;map:act type="sunRise-loggedIn"&gt;  &lt;!-- check authentication --&gt;
          &lt;map:parameter name="handler" value="myhandler"/&gt;
  
          &lt;map:act type="sunRise-auth"&gt;  &lt;!-- give access to the context --&gt;
              &lt;map:parameter name="handler" value="myhandler"/&gt;
  
              &lt;map:generate src="getinfofromcontext.xml"/&gt;
              &lt;map:transform src="sunRise"/&gt;
              &lt;map:transform src="toHTML"/&gt;
              &lt;map:serialize/&gt;
          &lt;/map:act&gt;
      &lt;/map:act&gt;
  
  &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
    
  
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/sunshine.html
  
  Index: sunshine.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>sunShine Session Management</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">sunShine Session Management</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Dev Guide</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Webapps</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Overview</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="authentication.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../howto/xmlform-wizard/howto-xmlform-wizard.html">Form Handling</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="portal.html">Portal</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Scratchpad</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Session Contexts</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunrise.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunspot.html">Portal</a></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
      
      
    <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Introduction</font>
  <hr style="color: #0086b2" size="1">
      
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i><b>IMPORTANT:</b> sunShine (= session framework) is part of the scratchpad area 
         of the current Cocoon
         release. This means it is not officially released yet. The API and functionality might change
          before it is moved into the official release. Using this is at your own risk!
          If you want to catch the latest status of these components check out Cocoon 
          from CVS and have a look at this <a href="session.html">upto-date documentation</a>.
      </i></font></td>
  </tr>
  </table>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A session is a data storage which resides on the server and records
          information about one single user. sunShine creates a session on demand and
          from that point of time the user is tracked and information can be stored
          inside the session. Each following request of this user is linked to the one
          specific session, so there is always only one session per user on the
          server.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">To avoid a fast growing amount of sessions on the server and the
          overcome potential security problems, a session has usually a valid period of
          time. If during this period no new request comes in from the user, the session
          object on the server will be destroyed by the server (this time period is
          called session timeout). The web application often allows a user to explictly
          destroy a session.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The usual web applications create sessions during login of a user and
          destroy them when the user logs out.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This document describes the basic sunShine session management using
          the sunShine Transformer.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The chapter "Special Contexts" explains some special sunShine
          contexts which do not require a session. They are available everytime. These
          special contexts are the request context, the response context and the
          temporary context.</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Sessions</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The sunShine-session actions is responsible for creating and
          terminating a session. It is controlled by a sitemap parameter named "action".
          This parameter can have the values "create" and "terminate". If no parameter is
          set, it defaults to "create".</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The action either creates a new session immediately (if not already
          available), or terminates it (if available).</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Contexts</font>
  <hr style="color: #0086b2" size="1">
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>sunShine Transformer</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The sunShine transformer is responsible for interpreting the tags
            and performing the actions required. The sunShine transformer is configured
            into the sitemap and can be used inside a document. All tags must be prefixed
            with the sunShine namespace. So the actual tag used in the document will read
            <i>&lt;sunshine:xxxx&gt;</i>. The current namespace URI for sunShine is
            <i>"http://cocoon.apache.org/sunshine/1.0"</i>.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Context-Tags</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A context is basically an application specific block of XML data in
            the users session. Each context has a unique name.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The command <i>createcontext</i> is used to create a new context.
            A <i>name</i> attribute must be given to the context in order to identify it.
            The following names may not be used: sunShine, request, response, session,
            context, temp, sunSpot or sunRise. If a context of the same name already exists
            then this command will have no effect.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;createcontext name="mycontext"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In order to delete a context the command <i>deletecontext</i> is
            provided. Again a <i>name</i> attribute must be provided.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;deletecontext name="mycontext"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Once created, XML data can then be stored inside or read from a
            given context.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Accessing context data</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The data in a context can be dynamically accessed using the
            following commands.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>getxml</i> allows data to be read out of a context. A
            <i>path</i> attribute describes the source of the data inside the context and
            consists of an XPath expression. All <i>path</i> values must be absolute and
            only nodes and attributes can be accessed. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">An optional default value can also be provided to allow for the
            nonexistence of the requested data.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="mycontext"
            path="/User/Name"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="mycontext"
            path="/User/Name"&gt;Matthew&lt;/getxml&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Attributes can also be accessed.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="mycontext"
            path="/User/Name/@Age"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i></i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Data can be written into a context using the <i>setxml</i>
            command. It is possible to set values or nodes as the following examples
            show.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;setxml context="mycontext"
            path="/User/Name"/&gt;Carsten&lt;/setxml&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;setxml context="mycontext"
            path="/User/"/&gt;&lt;Name&gt;Carsten&lt;/Name&gt;&lt;/setxml&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the <i>setxml</i> command causes all the nodes below the
            target node to be deleted. If you wish to maintain the nodes and manipulate
            individual branches of the XML tree - then sunShine offers the
            <i>mergexml</i> command.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Use the <i>removexml</i> command to remove nodes from the
            context.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;removexml context="mycontext"
            path="/User/"/&gt;</i></font>
  </p>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Example</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The following example shows the use of several commands and in
               particular how the <i>mergexml</i> command can be used to manipulate context
               data.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;resource xmlns:sunshine="http://cocoon.apache.org/sunshine/1.0"&gt;
    &lt;sunshine:createcontext name="trackdemo"/&gt;
  
    &lt;!-- build context data --&gt;
    &lt;sunshine:setxml context="trackdemo" path="/"&gt;
      &lt;context&gt;
        &lt;users&gt;
          &lt;user id="1"&gt;
            &lt;name&gt;Carsten&lt;/name&gt;
          &lt;/user&gt;
        &lt;/users&gt;
      &lt;/context&gt;
    &lt;/sunshine:setxml&gt;
  
    &lt;sunshine:mergexml context="trackdemo" path="/context"&gt;
      &lt;users&gt;
        &lt;user id="1"&gt;
          &lt;name&gt;Ziegeler&lt;/name&gt;
          &lt;developer&gt;true&lt;/developer&gt;
        &lt;/user&gt;
        &lt;user id="2"&gt;
          &lt;name&gt;Walter&lt;/name&gt;
        &lt;/user&gt;
      &lt;/users&gt;
    &lt;/sunshine:mergexml&gt;
  
    &lt;sunshine:getxml context="trackdemo" path="/"/&gt;
  &lt;/resource&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In the above example, a context for storing data is added. Using
               the <i>setxml</i> command data is then stored into the context. The following
               <i>mergexml</i> command then changes the name of user-1 and adds a further
               tag. As there is no original user-2 the complete subtree is then added to the
               context.</font>
  </p>
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Reading and writing contexts</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Aside from the described means of accessing data in a context,
            sunShine also provides for the reading and writing of contexts. This can be
            used to write an application context out to a database or to read an
            application context in from a file.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunShine offers a very flexible way of defining the source of the
            context data. It is possible to specify a resource (defined in the sitemap) or
            a Java class. Using a resource allows for example the context data to be read
            from a database using the SQL Transformer. As this source is a sunShine
            resource, the data can be generated and transformed before passing into the
            context. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">When a context is created, it can get additional save and load URIs
            which are used for loading/saving to/from the context:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;createcontext name="mycontext" load="cocoon://load-from-db"
            save="cocoon://save-to-db"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">These URIs can then be used inside a document to load data into a
            context:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;loadxml context="mycontext"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This example would then load the context data via the resource
            <i>load-from-db</i> which must be defined in the sitemap.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Parameters can be passed to and interpreted by the uri or the Java
            class. This allows the context data to be read dependent on say the current
            user.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;loadxml
            context="mycontext"&gt;&lt;user&gt;ben&lt;/user&gt;&lt;/loadxml&gt;</i></font>
  </p>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The resource addressed by the uri will receive the parameters as
            request-parameters. In addition the name of the context will always be passed
            as <i>contextname</i>.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Writing context data works in the same manner.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;savexml context="mycontext"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Both commands can use the optional <i>path</i> attribute:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;loadxml context="mycontext" path="/user"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;savexml context="mycotnext" path="/user"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The first command will read xml from the uri and store it in the
            context under the node <i>user</i>, the second one saves only the xml subtree
            under the node <i>user</i> to the uri. The resource addressed by the uri will
            be passed in addition to the <i>contextname</i> parameter the <i>path</i>
            parameter with the corresponding value. If the <i>path</i> attribute is not
            present the <i>path</i> parameter will get the value <i>"/"</i>.</font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Special Contexts</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunShine creates and maintains special contexts that allow the
          applications to access the environment data. This allows the read-only access
          to such things as the HttpRequest or the HtppResponse using the same XPath
          commands previously described. These context do not require any session, they
          are everytime available.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Request Context - Accessing the Environment, Part One</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The request context is an XML description of the current
            HttpRequest. This context is a special read only context which can be accessed
            with the usual commands:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="request" path="/parameter"/&gt;</i></font>
  </p>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you for example want to get the value of a parameter with the
            name <i>username</i> you can include the following command in your XML and it
            will be replaced with the value of the parameter:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="request"
            path="/parameter/username"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This command will be replaced with all parameters from the current
            request in XML format. If you wish to obtain the complete querystring as it was
            passed into sunShine - without converting the data to XML - then you can use
            the "/querystring" path:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;getxml context="request"
            path="/querystring"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The result will be a string in the format
            "?param=aaa&amp;...".</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The complete context you can access via these commands has the
            following XML format:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;parameter&gt;
    &lt;-- All parameters: parameter names build the elements
        with the values as text node childs --&gt;
    &lt;firstparameter&gt;value of parameter&lt;/firstparameter&gt;
    &lt;secondparameter&gt;value of parameter&lt;/secondparameter&gt;
  &lt;/parameter&gt;
  
  &lt;-- The querystring contains only parameters send by the GET method --&gt;
  &lt;querystring&gt;the querystring with a leading '?' or empty&lt;querystring&gt;
  
  &lt;-- All parameters. The tags are all inside the sunshine namespace.
       The generated xml can be used without modification for the
       sunshine:connection command. --&gt;
  &lt;parametervalues&gt;
    &lt;sunshine:params&gt;
      &lt;sunshine:param&gt;
        &lt;sunshine:name&gt;1st parameter name&lt;/sunshine:name&gt;
        &lt;sunshine:value&gt;1st parameter value&lt;/sunshine:value&gt;
      &lt;/sunshine:param&gt;
      ...
      &lt;sunshine:param&gt;
        &lt;sunshine:name&gt;2nd parameter name&lt;/sunshine:name&gt;
        &lt;sunshine:value&gt;2nd parameter value&lt;/sunshine:value&gt;
      &lt;/sunshine:param&gt;
    &lt;/sunshine:params&gt;
  
    &lt;!-- If a parameter has more than one value, for each value a
         &lt;sunshine:param&gt; block is generated. --&gt;
  &lt;/parametervalues&gt;
  
  &lt;!-- lists all attributes, attribute names build the elements
       with the values as text node childs --&gt;
  &lt;attributes&gt;
  &lt;/attributes&gt;
  
  &lt;!-- lists all headers, header names build the elements
       with the values as text node childs --&gt;
  &lt;headers&gt;
  &lt;/headers&gt;
  
  &lt;!-- lists all cookies --&gt;
  &lt;cookies&gt;
    &lt;cookie name="..."&gt;
      &lt;value&gt;the cookie value&lt;/value&gt;
      &lt;name&gt;the name of the cookie&lt;/name&gt;
      &lt;comment&gt;value&lt;/comment&gt;
      &lt;domain&gt;value&lt;/domain&gt;
      &lt;path&gt;value&lt;/path&gt;
      &lt;maxAge&gt;value&lt;/maxAge&gt;
      &lt;secure&gt;value&lt;/secure&gt;
      &lt;version&gt;value&lt;/version&gt;
    &lt;/cookie&gt;
  &lt;/cookies&gt;
  
  &lt;characterEncoding&gt;value&lt;/characterEncoding&gt;
  &lt;contentLength&gt;value&lt;/contentLength&gt;
  &lt;contentType&gt;value&lt;/contentType&gt;
  &lt;protocol&gt;value&lt;/protocol&gt;
  &lt;remoteAddress&gt;value&lt;/remoteAddress&gt;
  &lt;remoteHost&gt;value&lt;/remoteHost&gt;
  &lt;scheme&gt;value&lt;/scheme&gt;
  &lt;serverName&gt;value&lt;/serverName&gt;
  &lt;serverPort&gt;value&lt;/serverPort&gt;
  &lt;authType&gt;value&lt;/authType&gt;
  &lt;method&gt;value&lt;/method&gt;
  &lt;contextPath&gt;value&lt;/contextPath&gt;
  &lt;pathInfo&gt;value&lt;/pathInfo&gt;
  &lt;pathTranslated&gt;value&lt;/pathTranslated&gt;
  &lt;remoteUser&gt;value&lt;/remoteUser&gt;
  &lt;requestedSessionId&gt;value&lt;/requestedSessionId&gt;
  &lt;requestURI&gt;value&lt;/requestURI&gt;
  &lt;servletPath&gt;value&lt;/servletPath&gt;
  &lt;isRequestedSessionIdFromCookie&gt;value&lt;/isRequestedSessionIdFromCookie&gt;
  &lt;isRequestedSessionIdFromCookie&gt;value&lt;/isRequestedSessionIdFromCookie&gt;
  &lt;isRequestedSessionIdValid&gt;value&lt;/isRequestedSessionIdValid&gt;
    </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Response Context - Accessing the Environment, Part Two</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The response context is an XML description of the current
            HttpResponse. This context is a special write only context which can be
            accessed with the usual commands:</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"><i>&lt;sunshine:setxml context="response"
            path="/header"/&gt;</i></font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This command will be removed from the XML and the information will
            be added to the response. Using the response context headers and cookies can be
            added.</font>
  </p>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Adding headers</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Headers can be added either by <i>setxml</i> or by
               <i>appendxml</i>. If <i>setxml</i> is used, the header with the name gets
               the given value, regardless if the header had any value beforehand or not. If
               <i>appendxml</i> is used the value will be added.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;sunshine:setxml context="response"
                   path="/header/headername"&gt;The value&lt;/sunshine:setxml&gt;
  
     or
  
  &lt;sunshine:appendxml context="response"
                      path="/header/headername"&gt;The value&lt;/sunshine:appendxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">Adding cookies</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Cookies can be added either by setxml or by appendxml. There is
               no difference between these commands.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;sunshine:setxml context="response" path="/cookie"&gt;
    &lt;!-- Now follows the cookie definition --&gt;
    &lt;name&gt;The cookie name&lt;/name&gt;
    &lt;value&gt;The value of the cookie&lt;/value&gt;
  
    &lt;!-- The following are optional --&gt;
    &lt;path&gt;value&lt;/path&gt;
    &lt;domain&gt;value&lt;/domain&gt;
    &lt;secure&gt;true or false&lt;/secure&gt;
    &lt;comment&gt;value&lt;/comment&gt;
    &lt;maxAge&gt;value&lt;/maxAge&gt;
    &lt;version&gt;value&lt;/version&gt;
  &lt;/sunshine:setxml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Temporary Context</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The temporary context with the name <i>"temp"</i> is available on
            each request. It is independent from the session and has no content when a new
            request starts. It can be used like any other context except that the content
            is lost when the current response is finished.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the tempory context it is possible to use store any xml
            information for processing the current request.</font>
  </p>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Form Handling</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">To get feedback or information from a user, forms are commonly used
          to present input field in the browser. The usual approach for form handling in
          web application consists of two steps. The first request presents the form to
          the user. This form initiates a second request that processes the form
          values.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunShine supports this two step process, in addition sunShine offers
          a single step approach.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The common approach</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The common approach consists of two steps or of creating two
            resources. The first resource defines the form: All input fields are declared,
            each gets a unique name. This form invokes the second resource.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This resource uses the sunShine transformer to get the values
            provided by the user. The values are added by the browser to the parameters of
            the request. So using the request context and <i>getxml</i>, the values can
            be fetched.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you want to create a form with two values - forename and surname
            of the user, you could generate a base xml file with the information about this
            form:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;page&gt;
    &lt;form&gt;
      &lt;action&gt;form-handling-page&lt;/action&gt;
      &lt;input name="forename" type="text"/&gt;
      &lt;input name="surname" type="text"/&gt;
    &lt;/form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A stylesheet can transform this into valid html. The action tag
            indicates that the "form-handling-page" should be invoked by submitting the
            values.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The "form-handling-page" is a pipeline which is declared in the
            sitemap and uses the sunShine transformer. It could also read the following
            xml:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;page xmlns:sunshine="http://cocoon.apache.org/sunshine/1.0"&gt;
    &lt;forename&gt;
      &lt;sunshine:getxml context="request" path="/parameter/forename"/&gt;
    &lt;/forename&gt;
    &lt;surname&gt;
      &lt;sunshine:getxml context="request" path="/parameter/surname"/&gt;
    &lt;/surname&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">As the form values are appended to the request, <i>getxml</i>
            with specifying the path (which is the parameter name used for the input field)
            inserts the value submitted by the user into the xml stream.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you want to write the information in a session context, you must
            wrap the whole xml inside a setxml:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;page xmlns:sunshine="http://cocoon.apache.org/sunshine/1.0"&gt;
    &lt;sunshine:setxml context="userdata" path="/user"&gt;
      &lt;forename&gt;
        &lt;sunshine:getxml context="request" path="/parameter/forename"/&gt;
      &lt;/forename&gt;
      &lt;surname&gt;
        &lt;sunshine:getxml context="request" path="/parameter/surname"/&gt;
      &lt;/surname&gt;
    &lt;/sunshine:setxml&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The user data is now stored inside the session context "userdata",
            so the context has the following content:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;user&gt;
    &lt;forename&gt;Walter&lt;/forename&gt;
    &lt;surname&gt;Walterson&lt;/surname&gt;
  &lt;/user&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The sunShine approach</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The previous chapter showed the common approach for handling form
            values. It forces the user to create two resources for a single form
            handling.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunShine offers an advanced approach. Only one single resource is
            created. This resources contains the information about the input fields used
            and in addition the information about where the submitted values should be
            stored inside the session.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The example from the previous chapter could look like this:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;page xmlns:sunshine="http://cocoon.apache.org/sunshine/1.0"&gt;
    &lt;sunshine:form name="myform"&gt;
      &lt;sunshine:action&gt;the-next-page&lt;/sunshine:action&gt;
      &lt;sunshine:content&gt;
        &lt;sunshine:inputxml name="forename" type="text"
                           context="userdata" path="/user/forename"/&gt;
        &lt;sunshine:inputxml name="surname" type="text"
                           context="userdata" path="/user/surname"/&gt;
      &lt;/sunshine:content&gt;
    &lt;/sunshine:form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The form tag starts the form definition. The name attribute is
            required to distinct between different forms on the same page. The action tag
            defines the url invoked by the form and the content tag describes the content
            of the form: its input fields.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The <i>inputxml</i> tag tells sunShine that the following request
            contains form values which should be stored in the specified context under the
            given path. The sunShine transformer transforms by removing the namespace and
            the context attribute:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;page xmlns:sunshine="http://cocoon.apache.org/sunshine/1.0"&gt;
    &lt;form action="the-next-page"&gt;
      &lt;inputxml name="forename" type="text"/&gt;
      &lt;inputxml name="surname" type="text"/&gt;
    &lt;/form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A stylesheet can now generate the appropriate html (or any other
            format). The main difference is, that the resource invoked by submitting the
            values has not to care about the form as sunShine maintains the form handling.
            The only prerequisit is that a session for the current user and a session
            context to store the information exists.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The sunShine approach allows a very easy way of form handling where
            the resource which creates the form also handles the form.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For editing values - if the context already contains information
            about the user - <i>inputxml</i> inserts the current value inside the tag. So
            the xml streamed would after a second run would look like this:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;page xmlns:sunshine="http://cocoon.apache.org/sunshine/1.0"&gt;
    &lt;form action="the-next-page"&gt;
      &lt;inputxml name="forename" type="text"&gt;Walter&lt;/inputxml&gt;
      &lt;inputxml name="surname" type="text"&gt;Walterson&lt;/inputxml&gt;
    &lt;/form&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Like <i>getxml</i> it is also possible to provide default values
            for the input field, if the context does not contain any information:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;sunshine:inputxml name="forename" context="userdata"
                     path="/user/forename"&gt;
    Defaultname
  &lt;/sunshine:xml&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
  
       
    
  
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/sunspot.html
  
  Index: sunspot.html
  ===================================================================
  <html xmlns:NetUtils="org.apache.cocoon.util.NetUtils">
  <head>
  <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
  <title>Building Portals with sunSpot</title>
  <STYLE type="text/css">
  a.menu {
  	color: #FFFFFF;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:plain;
      text-decoration:none;
      padding-left: 14px
  }
  
  A.menu:hover {
  	color: #FFCC00
  }
  
  
  .menutitle {
  	color: #000000;
      text-align:left;               
      font-size:10px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 8px
  }
  .menuselected {
  	color: #FFCC00;
      text-align:left;               
      font-size:12px;
      font-family: Verdana, Arial, Helvetica, sans-serif;
      font-weight:bold;
      padding-left: 14px
  }
  </STYLE>
  </head>
  <body bgcolor="#ffffff" marginheight="4" marginwidth="4" leftmargin="4" topmargin="4" alink="#cc0000" vlink="#0086b2" link="#039acc" text="#000000">
  <table border="0" cellpadding="0" cellspacing="0" width="100%">
  <tr>
  <td align="left" valign="top" rowspan="3" height="60" width="135"><img border="0" vspace="0" hspace="0" src="images/logo.gif" height="60" width="135"></td><td background="images/line.gif" rowspan="1" colSpan="2" align="left" valign="top" height="0" width="100%"></td><td align="left" valign="top" rowspan="3" height="60" width="29"><img border="0" vspace="0" hspace="0" src="images/right.gif" height="60" width="29"></td>
  </tr>
  <tr>
  <td bgcolor="#0086b2" colspan="2" align="right" valign="top" height="35" width="100%"><font color="#ffffff" face="Verdana, Arial, Helvetica, sans-serif" size="5">Building Portals with sunSpot</font></td>
  </tr>
  <tr>
  <td background="images/bottom.gif" colspan="2" width="100%" valign="top" height="20" bgcolor="#0086b2" align="right">
  <table width="288" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td align="left" valign="top" height="20" width="96"><a target="new" href="http://xml.apache.org/"><img border="0" vspace="0" hspace="0" name="xml" src="images/button-xml-lo.gif" height="20" width="96" alt="http://xml.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.apache.org/"><img border="0" vspace="0" hspace="0" name="asf" src="images/button-asf-lo.gif" height="20" width="96" alt="http://www.apache.org/"></a></td><td align="left" valign="top" height="20" width="96"><a target="new" href="http://www.w3.org/"><img border="0" vspace="0" hspace="0" name="w3c" src="images/button-w3c-lo.gif" height="20" width="96" alt="http://www.w3.org/"></a></td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr width="100%">
  <td align="left" valign="top" width="120">
  <table width="120" cellspacing="0" cellpadding="0" border="0" bgcolor="#a0a0a0">
  <tr>
  <td valign="top" align="left"><img width="120" vspace="0" src="images/join.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../index.html">Main</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../index.html">Dev Guide</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Webapps</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="index.html">Overview</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="session.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="authentication.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="../../howto/xmlform-wizard/howto-xmlform-wizard.html">Form Handling</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="portal.html">Portal</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td background="images/label-background_b.gif" bgcolor="#959595" valign="top"><img width="120" height="6" src="images/separator.gif"><br>
  <span class="menutitle">Scratchpad</span></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunshine.html">Session Contexts</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><a class="menu" href="sunrise.html">Authentication</a></td>
  </tr>
  <tr xmlns:NetUtils="http://xml.apache.org/xslt/java/org.apache.cocoon.util.NetUtils">
  <td valign="top" bgcolor="#959595" background="images/label-background_a.gif"><span class="menuselected">Portal</span></td>
  </tr>
  <tr>
  <td align="left" valign="top"><img width="120" vspace="0" src="images/close.gif" hspace="0" height="14" border="0"><br>
  </td>
  </tr>
  </table>
  </td><td>
  <table cellspacing="15" cellpadding="0" border="0">
  <tr>
  <td>
      
      
    <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Introduction</font>
  <hr style="color: #0086b2" size="1">
      
  <p>
  <table border="0" cellpadding="0" cellspacing="3" width="100%">
  <tr>
  <td valign="top" width="28"><img alt="Note" border="0" hspace="0" vspace="0" height="29" width="28" src="images/note.gif"></td><td valign="top"><font color="black" face="verdana,helvetica,sanserif" size="-1"><i><b>IMPORTANT:</b> sunSpot (= portal framework) is part of the scratchpad area 
         of the current Cocoon
         release. This means it is not officially released yet. The API and functionality might change
          before it is moved into the official release. Using this is at your own risk!
          If you want to catch the latest status of these components check out Cocoon 
          from CVS and have a look at this <a href="portal.html">upto-date documentation</a>.
      </i></font></td>
  </tr>
  </table>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunSpot is the portal engine of sunShine. It provides the required
          functionality to display user dependent content with a user defineable
          layout.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The sunShine portal defintion framework is an XML description of the
          portal and the contained content. The rendering of the portal to the needed
          format (such as HTML) is done through stylesheets and is therefore very
          flexible.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A portal definition can be configured for all users (global), for
          groups of users (group or role) and for the individual user. The portal
          admininstrator can use the provided tools to configure every aspect of the
          portal (from colours to content).</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each "blob" of portal content is contained in a "sunLet". sunLets can
          be configured into the portal on a per-user or per-group basis allowing a
          flexible content definition.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunLets can be minimized, maximized or even removed by the user if he
          does not wish to see the content. However, the administrator may configure
          sunLets to be mandatory, in which case they may not be removed.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The different portals are administrated by sunRise applications. Each
          application can have its own portal.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This documentation explains the different resources for sunSpot, the
          configuration of a portal and how sunSpot creates the portal view derived from
          this information. After that all is put together by creating the needed entries
          in the sitemap for using and displaying a portal.</font>
  </p>
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">The Profile</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">A sunSpot portal is built upon a profile which contains all necessary
          information: the portal possibilites (the available sunLets, the possible
          changes to the layout etc.) and the portal view (the layout for this user and
          the sunLets he chose for himself). This profile is generated when a user logs
          into the application the portal belongs to. The building of the profile is a
          very flexible process which allows to have different configurations for
          different users.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In general the building of the profile consists of four steps:</font>
  </p>
  
       
  <blockquote>
  <ol>
          
  <li>
  <font face="verdana, helvetica, sans serif">Building the base profile. This profile defines which
            possibilites the portal has, which sunLets are available to the portal and
            which parts of the profile can be changed by the user.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">Building the global profile. The base profile is enhanced by a
            global delta which contains a predefined portal view. This predefined portal
            view is a starting point for all users.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">Building the role profile. The global profile is enhanced by a
            role delta which contains a predefined portal view. This predefined portal view
            is a starting point for all users of that role.
          </font>
  </li>
          
  <li>
  <font face="verdana, helvetica, sans serif">Building the user profile. The role profile is augmented by a
            user delta which contains the portal for this specific user. An optional user
            status profile with often changing information can optional be appended to the
            profile.
          </font>
  </li>
       
  </ol>
  </blockquote>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Only step 1 and 2 are mandatory for the building process. Steps 3 and
          4 are optional and depend on the configuration of the users and roles in the
          system.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each delta (steps 2, 3 and 4) can modify the possibilites of the
          portal and the configuration of the sunLets. But it is not allowed to add new
          features or sunLets. In addition a delta may contain a predefined portal
          view.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This building process is invoked each time the user logs into the
          application. So a change to any profile (delta) is incorporated into the user
          profile: If e.g. a sunLet , which a user has choosen for his portal view, is
          removed from the system, it is not available to the user anymore and therefore
          also removed from his portal view.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The global delta, the role delta and the user delta are very similar.
          They only differ in the name of the root node.</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Base Profile</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The base profile consists of three data sources:</font>
  </p>
          
  <blockquote>
  <ol>
            
  <li>
  <font face="verdana, helvetica, sans serif"> The layout profile describes the possibilites and layout of
               the portal.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The sunLets profile defines all available sunLets for the
               portal view.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The type profile describes the parts of the profile which can
               be changed by the user.
            </font>
  </li>
          
  </ol>
  </blockquote>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The Layout Profile</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The layout profile describes the overall layout of the portal
               including if header or footer are present which colors and fonts are used and
               so on.</font>
  </p>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">An example profile is shown below. The profile is enclosed in the
               root node "layout-profile" and consists of the "portal" part and the "sunlets"
               part:</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;layout-profile&gt;
      &lt;portal&gt; &lt;!-- This node contains the layout of the portal view --&gt;
                    &lt;layouts&gt;
  
                          &lt;layout&gt;
                     &lt;!-- The color of the background --&gt;
                                    &lt;background&gt;
                                         &lt;color&gt;#ffffff&lt;/color&gt;
                                    &lt;/background&gt;
                     &lt;!-- The font and color for usual text --&gt;
                                    &lt;font&gt;
                                         &lt;type&gt;Arial, Helvetica, sans-serif&lt;/type&gt;
                                         &lt;size&gt;2&lt;/size&gt;
                                         &lt;color&gt;black&lt;/color&gt;
                                    &lt;/font&gt;
                            &lt;/layout&gt;
                  &lt;/layouts&gt;
  
                    &lt;!-- The following means that the sunSpot portal has a header area --&gt;
                  &lt;header&gt;
                           &lt;exists&gt;true&lt;/exists&gt;
                  &lt;/header&gt;
  
                  &lt;!-- The following means that sunSpot has 3 columns --&gt;
                  &lt;columns&gt;
                           &lt;number&gt;3&lt;/number&gt;
                    &lt;/columns&gt;
  
                  &lt;!-- The following means that the sunSpot has not a footer area --&gt;
                  &lt;footer&gt;
                           &lt;exists&gt;false&lt;/exists&gt;
                  &lt;/footer&gt;
             &lt;/portal&gt;
  
             &lt;sunlets&gt; &lt;!-- This node contains the layout of the sunLets --&gt;
                &lt;layouts&gt;
                      &lt;layout&gt;
                              &lt;title&gt;  &lt;!-- The layout of the title --&gt;
                                     &lt;background&gt;
                                         &lt;color&gt;#46627A&lt;/color&gt;
                                     &lt;/background&gt;
                                     &lt;font&gt;
                                          &lt;type&gt;Arial&lt;/type&gt;
                                          &lt;size&gt;2&lt;/size&gt;
                                          &lt;color&gt;#ffffff&lt;/color&gt;
                                     &lt;/font&gt;
                              &lt;/title&gt;
  
               &lt;content&gt; &lt;!-- The layout of the content --&gt;
                                     &lt;font&gt;
                                          &lt;type&gt;Arial&lt;/type&gt;
                                          &lt;size&gt;2&lt;/size&gt;
                                          &lt;color&gt;#000000&lt;/color&gt;
                                     &lt;/font&gt;
                                  &lt;background&gt;
                                         &lt;color&gt;#ffffff&lt;/color&gt;
                                     &lt;/background&gt;
                              &lt;/content&gt;
                       &lt;/layout&gt;
                &lt;/layouts&gt;
            &lt;/sunlets&gt;
  
  &lt;/layout-profile&gt;
          </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The sunLets Profile</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The sunLets profile contains all sunLets which are available in
               the system. It is an XML based resource with the root node "sunlets-profile".
               All sunLets are defined under a node called "sunlets", so an example profile
               could look like this:</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>    &lt;sunlets-profile&gt;
          &lt;sunlets&gt;
              &lt;sunlet id="bankingnews"&gt;
                  &lt;resource uri="cocoon://sunlet-banking.xml"/&gt;
                  &lt;transformation&gt; &lt;!-- optional xsl transformation --&gt;
                      &lt;stylesheet&gt;sunbank/styles/sunlet.xsl&lt;/stylesheet&gt;
                  &lt;/transformation&gt;
                  &lt;configuration&gt;
                      &lt;mandatory&gt;false&lt;/mandatory&gt;
                      &lt;sizable&gt;true&lt;/sizable&gt;
                      &lt;active&gt;true&lt;/active&gt;
                      &lt;timeout&gt;5000&lt;/timeout&gt; &lt;!-- optional, milliseconds --&gt;
                      &lt;messages&gt;              &lt;!-- optional: Messages --&gt;
                          &lt;sunlet_not_available&gt;
                             Display this if the sunLet is not available.
                          &lt;/sunlet_not_available&gt;
                      &lt;/messages&gt;
                  &lt;/configuration&gt;
                  &lt;title&gt;Banking News&lt;/title&gt;
                  &lt;status&gt;
                      &lt;visible&gt;true&lt;/visible&gt;
                      &lt;size&gt;max&lt;/size&gt;
                  &lt;/status&gt;
              &lt;/sunlet&gt;
          &lt;/sunlets&gt;
      &lt;/sunlets-profile&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">This example defines one sunLet: the bankingnews sunLet with the
               title "Banking News". The title is displayed in the portal view above the
               sunLet content. The most important part is the resource definition. Using this
               resource the sunLet is displayed in the portalview of the user. </font>
  </p>
            
  <blockquote>
  <ul>
               
  <li>
  <font face="verdana, helvetica, sans serif">An uri, e.g.: &lt;resource uri=".."/&gt;. This URI can be a
                  local one which is retrieved using the sitemap or a distant one which is
                  retrieved using an HTTP request. In both cases the resource must deliver valid
                  XML for the sunLet content. If you don't use a protocol, the URI is assumed to
                  be a file.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">A java class delivering the content.
               </font>
  </li>
            
  </ul>
  </blockquote>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">There a several mandatory configuration parameters for a sunLet.
               This configuration parameters can only be changed by the portal administrator.
               The user cannot change them for his portal view.</font>
  </p>
            
  <blockquote>
  <ul>
               
  <li>
  <font face="verdana, helvetica, sans serif">mandatory: Indicates if the sunLet can be removed by the
                  user or if it is always visible.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">sizable: Is the sunLet sizable? If the value is true the
                  user can minimize this sunLet in his portal view.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">active: Using this parameter, a sunLet can be deactivated
                  for a distinct period of time. If a sunLet is not active it will not displayed
                  to the user even if he has configured it.
               </font>
  </li>
            
  </ul>
  </blockquote>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition there are some optional parameters:</font>
  </p>
            
  <blockquote>
  <ul>
               
  <li>
  <font face="verdana, helvetica, sans serif">timeout: This is the time in milliseconds, sunSpot waits to
                  get the sunLet content. If the content is not available within this time frame,
                  the sunLet is declared as not available at the moment. The default value for
                  the timeout can be set in the sunSpot configuration (see next chapter).
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">handlesSizable: If this value is true, the sunLet (or
                  better the resource) handles the sizing of this sunLet itselt. This means it
                  determines the data to be displayed if the sunLet is minimized or maximized. If
                  this value is false sunSpot displayes the whole sunLet if it is maximized and
                  only its title if it is minimized. This is the default behaviour.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">handlesParameters: If this value is true (which is the
                  default value) the resource gets all configuration and status parameters
                  passed, e.g. if the resource is an uri, the parameters are passed as HTTP
                  request parameters.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">messages/sunlet_not_available: If the sunLet is not
                  available (e.g. external data where the server is not available), a message is
                  displayed. With this optional parameter each sunlet can get a distinct message
                  which overrides the message provided by the user profile.
               </font>
  </li>
            
  </ul>
  </blockquote>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The status parameters can be changed by the user for configuring
               his own portal view:</font>
  </p>
            
  <blockquote>
  <ul>
               
  <li>
  <font face="verdana, helvetica, sans serif">visible: If a sunLet is visible it is included in the
                  portal view. If it is not visible it is still configured for the user but it
                  will not displayed.
               </font>
  </li>
               
  <li>
  <font face="verdana, helvetica, sans serif">size: Currently two sizes (min and max) are distinquished.
               </font>
  </li>
            
  </ul>
  </blockquote>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the source of the sunLet needs additional transformation there
               are two possibilities for doing the transformation. The first one is creating a
               pipeline in the sitemap for this sunLet and the second one usses the sunLet
               configuration for this. As the first one is the usual sunShine pipeline
               creating process only the second one is covered here.</font>
  </p>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">By defining the "transformation" node inside the "sunlet" node,
               the source of the sunLet can be transformed with one or more stylesheets. For
               each stylesheet a "stylesheet" node with the value of the stylesheet path has
               to be created. The order of appearance determines the order of processing. If
               e.g. the source of a sunLet is a class or a file, there is no need to specify a
               pipeline only for this sunLet. Specifying a file/class as source and a
               "stylesheet" node has the same effect.</font>
  </p>
            
  <font face="verdana, helvetica, sans serif" color="#0086b2"><b>Adding a new sunLet</b></font>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Adding new information to the portal requires four basic
                  steps:</font>
  </p>
               
  <blockquote>
  <ul>
                  
  <li>
  <font face="verdana, helvetica, sans serif">Defining the resource containing the information. For
                    external resources only the address (mainly an URI) and the protocol (usually
                    HTTP) is required. Otherwise a new XML resource has to be created with the new
                    content.
                  </font>
  </li>
                  
  <li>
  <font face="verdana, helvetica, sans serif">Defining the stylesheet for the presentation of this
                    content.
                  </font>
  </li>
                  
  <li>
  <font face="verdana, helvetica, sans serif">For local resources: Definition of the pipeline in the
                    sitemap. This pipeline must contain all necessary steps for building the
                    information. It must deliver XML as the serialized format.
                  </font>
  </li>
                  
  <li>
  <font face="verdana, helvetica, sans serif">Adding a new "sunlet" node to the sunLets profile.
                  </font>
  </li>
               
  </ul>
  </blockquote>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">After these steps are finished, the new sunLet is automatically
                  available for each user which logs in after the addition. If the sunLet is even
                  mandatory it will be added to the portal view of the user.</font>
  </p>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For more information see the chapter "The Pipelines".</font>
  </p>
            
            
  <font face="verdana, helvetica, sans serif" color="#0086b2"><b>Customizable sunLets</b></font>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each sunLet can have its own configuration, e.g. a weather
                  sunLet should display the weather for a particular city etc.</font>
  </p>
               
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>    &lt;sunlets-profile&gt;
          &lt;sunlets&gt;
              &lt;sunlet id="bankingnews"&gt;
                  &lt;resource uri="cocoon://sunlet-banking.xml"/&gt;
                  &lt;customization uri="cocoon://customize-sunlet-banking.xml"/&gt; &lt;!-- optional --&gt;
                  &lt;transformation&gt; &lt;!-- optional xsl transformation --&gt;
                      &lt;stylesheet&gt;sunbank/styles/sunlet.xsl&lt;/stylesheet&gt;
                  &lt;/transformation&gt;
                  &lt;configuration&gt;
                      &lt;mandatory&gt;false&lt;/mandatory&gt;
                      &lt;sizable&gt;true&lt;/sizable&gt;
                      &lt;active&gt;true&lt;/active&gt;
                      &lt;timeout&gt;5000&lt;/timeout&gt; &lt;!-- optional, milliseconds --&gt;
                      &lt;messages&gt;              &lt;!-- optional: Messages --&gt;
                          &lt;sunlet_not_available&gt;
                             Display this if the sunLet is not available.
                          &lt;/sunlet_not_available&gt;
                      &lt;/messages&gt;
                      &lt;customizable&gt;true&lt;/customizable&gt; &lt;!-- optional --&gt;
                      &lt;persistent&gt;false&lt;/persistent&gt;    &lt;!-- optional --&gt;
                  &lt;/configuration&gt;
                  &lt;title&gt;Banking News&lt;/title&gt;
                  &lt;status&gt;
                      &lt;visible&gt;true&lt;/visible&gt;
                      &lt;size&gt;max&lt;/size&gt;
                  &lt;/status&gt;
              &lt;/sunlet&gt;
          &lt;/sunlets&gt;
      &lt;/sunlets-profile&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">To declare a sunLet as customizable it must get a configuration
                  resource which is displayed to a user of this sunLet to enter all required
                  configuration values. This is done with the <i>customization</i> tag. The
                  value for this tag has the same possibilities as the <i>resource</i> tag,
                  usually the <i>uri</i> attribute points to a pipeline.</font>
  </p>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">When a user has configured/choosen a customizable sunLet,
                  sunSpot detects if this sunLet has its configuration. If it does not have one,
                  the customization resource of the sunLet is displayed in the portal view.
                  Otherwise the sunLet itself is displayed.</font>
  </p>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition a customizable sunLet can be persistent, e.g. the
                  configuration is saved for a longer period than the current session of the
                  user. If the sunLet is not persistent the configuration is lost when the user
                  logs out. The next time he logs in, the customization page is displayed to
                  configure this sunLet again.</font>
  </p>
               
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If you use persistent sunLets you have to configure resources
                  for loading and saving the status profile (See configuration). More about
                  writing customizable sunLets can be found in the chapter "Writing Customizable
                  sunLets".</font>
  </p>
            
          
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The Type Profile</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The type profile describes the possible values the user can
               change for his portal view. Using this flexible approach the portal
               administrator can decide which user can choose what. For example, a normal user
               might change the layout and content of his portal view, but a guest might not
               be allowed to change anything, whereas the administrator can change
               everything.</font>
  </p>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The type profile is surrounded by the root node "type-profile".
               It consists of two parts: the typedefs section and the elements section. The
               type profile can be compared with a programming language. The typedefs section
               declares all available types and the the elements section declares all
               variables with their corresponding types. A "variable" defines a place or
               element in the user profile which can be changed by the user. The possibilites
               for this element are defined by the type.</font>
  </p>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The typedefs contains enumerations, e.g. a set of possible values
               with a user presentable name. In addition sunSpot has the following predefined
               types: STRING (arbitrary text), BOOLEAN (true or false), INTEGER (a number) and
               CARDINAL (a positiv number).</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;type-profile&gt;
  
       &lt;typedefs&gt;
                  &lt;!-- The following types are defined by sunSpot: (Names are casesensitiv!)
                            STRING, BOOLEAN, ENUMERATION, INTEGER, CARDINAL --&gt;
  
            &lt;typedef name="backgroundcolor" type="ENUMERATION"&gt;
                      &lt;value name="weiss"&gt;#ffffff&lt;/value&gt;
                      &lt;value name="hellgrau"&gt;#cccccc&lt;/value&gt;
                      &lt;value name="hellgruen"&gt;#aab9bf&lt;/value&gt;
                      &lt;value name="dunkelgruen"&gt;#46627A&lt;/value&gt;
                  &lt;/typedef&gt;
                  &lt;typedef name="textcolor" type="ENUMERATION"&gt;
                      &lt;value name="weiss"&gt;white&lt;/value&gt;
                      &lt;value name="schwarz"&gt;black&lt;/value&gt;
                      &lt;value name="weiss"&gt;#ffffff&lt;/value&gt;
                      &lt;value name="hellgrau"&gt;#cccccc&lt;/value&gt;
                      &lt;value name="hellgruen"&gt;#aab9bf&lt;/value&gt;
                      &lt;value name="dunkelgruen"&gt;#46627A&lt;/value&gt;
                  &lt;/typedef&gt;
                  &lt;typedef name="sunletsize" type="ENUMERATION"&gt;
                      &lt;value name="Maximized"&gt;max&lt;/value&gt;
                      &lt;value name="Minimized"&gt;min&lt;/value&gt;
                  &lt;/typedef&gt;
                  &lt;typedef name="columnnumber" type="ENUMERATION"&gt;
                      &lt;value name="1"&gt;1&lt;/value&gt;
                      &lt;value name="2"&gt;2&lt;/value&gt;
                      &lt;value name="3"&gt;3&lt;/value&gt;
                      &lt;value name="4"&gt;4&lt;/value&gt;
                      &lt;value name="5"&gt;5&lt;/value&gt;
                  &lt;/typedef&gt;
      &lt;/typedefs&gt;
  
  &lt;/type-profile&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The element section has the same structure a the user profile.
               For each leave which is changeable by the user the elements section contains an
               entry for the type of this node. The node is enhanced by two attributes: type
               for the node type and description for a user readable title. This information
               is used by sunSpot to present the configuration screen for the portal. It
               displayes for each changeable leave a form field with the corresponding
               type.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>
  &lt;type-profile&gt;
          &lt;elements&gt;
                 &lt;layout-profile&gt;
                     &lt;portal&gt;&lt;layouts&gt;
                            &lt;layout&gt;
                       &lt;!-- The user can change the background.
                            The possible values are taken from the enumeration
                            backgroundcolor. The user gets the title "Background"
                            displayed for the form field. --&gt;
                              &lt;background&gt;
                                       &lt;color type="backgroundcolor" description="Background"/&gt;
                               &lt;/background&gt;
                          &lt;font&gt;
                           &lt;color type="textcolor" description="Font color"/&gt;
                                &lt;/font&gt;
                            &lt;/layout&gt;
                          &lt;/layouts&gt;
                           &lt;columns&gt;
                      &lt;!-- The user can change the number of columns --&gt;
                      &lt;number type="columnnumber" description="Number of columns"/&gt;
                  &lt;/columns&gt;
                     &lt;/portal&gt;
                 &lt;/layout-profile&gt;
  
           &lt;portal-profile&gt;
                      &lt;content&gt;
                   &lt;!-- Using the * the following configuration is applied for
                        all columns regardless of their position. --&gt;
                              &lt;column position="*"&gt;
                                      &lt;width type="CARDINAL" description="Width"/&gt;
                                      &lt;sunlets&gt;
                           &lt;!-- Using the * the following configuration is applied for
                                each sunlet. --&gt;
                                          &lt;sunlet id="*" position="*" number="*"&gt;
                                              &lt;status&gt;
                               &lt;!-- The user can change the visibility and size
                                    of the sunLet --&gt;
                                                      &lt;visible type="BOOLEAN" description="Visible"/&gt;
                                                      &lt;size type="sunletsize" description="Size"/&gt;
                                          &lt;/status&gt;
                                          &lt;/sunlet&gt;
                                  &lt;/sunlets&gt;
                              &lt;/column&gt;
                      &lt;/content&gt;
                 &lt;/portal-profile&gt;
          &lt;/elements&gt;
  &lt;/type-profile&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The Global Profile</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The global delta, the role delta and the user delta are very
            similar. They only differ in the name of the root node. So this chapter only
            describes the global delta and points out the differences between the deltas at
            the various place rather than repeating the same information in different
            chapters.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The global delta is enclosed in the root node "global-delta", the
            role delta uses the node "role-delta" and the user delta the node
            "user-delta".</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In general a delta defines the differences between two profiles.
            The sunSpot deltas allow only adding and changing but not removing nodes. Each
            delta can contain the following parts: </font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">The layout delta containing the difference to the layout
               profile.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The sunlets delta describing the differences to the sunlets
               profile.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The portal profile containing a complete portal view. This
               part is not a delta. If it is contained in a delta and the profile already has
               this information, that information is replaced by the one from the delta.
               Otherwise the delta information is added. For the global profile the portal
               profile is mandatory.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">The personal profile. This part contains personal information
               of the user, e.g. are welcome text. For the global profile this information
               again is mandatory. It defines the possibilites the user has. The role and the
               user profile can only change this information. But they cannot add any new
               nodes.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"> So here is an example:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;global-delta&gt;
         &lt;!-- No difference to the base profile --&gt;
      &lt;layout-delta&gt;
         &lt;/layout-delta&gt;
  
         &lt;!-- No difference to the base profile --&gt;
         &lt;sunlets-delta&gt;
         &lt;/sunlets-delta&gt;
  
      &lt;!-- This is the starting portal view for all users.
           It has to be defined in the global profile --&gt;
      &lt;portal-profile&gt;
  
          &lt;!-- This is the content of the portal view --&gt;
             &lt;content&gt;
                    &lt;header&gt;
                            &lt;sunlet id="personalize" position="1"&gt;
                                   &lt;status&gt;
                                            &lt;visible&gt;true&lt;/visible&gt;
                                            &lt;size&gt;max&lt;/size&gt;
                                  &lt;/status&gt;
                              &lt;/sunlet&gt;
                    &lt;/header&gt;
                    &lt;column position="1"&gt;
                           &lt;width&gt;28%&lt;/width&gt;
                                                                  &lt;!-- The sunLets are displayed in the order of their
                       position attribute in each column. --&gt;
                           &lt;sunlets&gt;
                                &lt;sunlet id="administration" number="1" position="1"&gt;
                                       &lt;status&gt;
                                                &lt;visible&gt;true&lt;/visible&gt;
                                              &lt;size&gt;max&lt;/size&gt;
                                         &lt;/status&gt;
                                  &lt;/sunlet&gt;
                           &lt;/sunlets&gt;
                    &lt;/column&gt;
  
                    &lt;column position="2"&gt;
                           &lt;width&gt;50%&lt;/width&gt;
                               &lt;sunlets&gt;
                                  &lt;sunlet id="banknews" number="2" position="1"/&gt;
                              &lt;/sunlets&gt;
                  &lt;/column&gt;
  
                    &lt;column position="3"&gt;
                           &lt;width&gt;22%&lt;/width&gt;
                           &lt;sunlets/&gt;
                  &lt;/column&gt;
          &lt;/content&gt;
  &lt;/portal-profile&gt;
  
  &lt;personal-profile&gt;
         &lt;greeting&gt;Herzlich willkommen&lt;/greeting&gt;
         &lt;messages&gt;
                &lt;sunlet_not_available&gt;Das sunLet ist zur Zeit nicht verfuegbar.&lt;/sunlet_not_available&gt;
         &lt;/messages&gt;
  &lt;/personal-profile&gt;
  
  &lt;/global-delta&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>The User Status Profile</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The user status profile contains often changing information like
            the configuration of configurable sunLets, the last login time etc. The user
            status profile is optional, but if it is not accessible, customizable sunLets
            are not possible.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For each customizable sunLet which is in the portal view of the
            user the status profile contains an XML block with the sunLet specific
            configuration for this sunLet.</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;status-profile&gt;
      &lt;customization&gt;
          &lt;!-- Custom information for each customizable sunLet --&gt;
          &lt;sunlet id="popmail" number="3"&gt;
              &lt;host&gt;mail&lt;/host&gt;
              &lt;password&gt;gsgdgsg&lt;/password&gt;
              &lt;mailcount&gt;4&lt;/mailcount&gt;
              &lt;user&gt;walter&lt;/user&gt;
          &lt;/sunlet&gt;
      &lt;/customization&gt;
  &lt;/status-profile&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">Configuring sunSpot</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The configuration of sunSpot is actually a sunRise application
          configuration. Please refer to the sunRise documentation for more information
          about sunRise handler and application configuration.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Inside your sunRise handler configuration you define for each portal
          an application configuration for sunSpot like the example portal called
          "sunBank" below: </font>
  </p>
       
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>    &lt;application name="sunBank"&gt;
          &lt;configuration name="sunSpot"&gt; &lt;!-- This is the portal configuration --&gt;
              &lt;portal-uri&gt;finance-portal&lt;/portal-uri&gt;
              &lt;profile-cache&gt;true&lt;/profile-cache&gt;
              &lt;process-sunlets-parallel&gt;false&lt;/process-sunlets-parallel&gt;
              &lt;default-sunlet-timeout&gt;10000&lt;/default-sunlet-timeout&gt;
              &lt;profile&gt;
                  &lt;!-- The resource for loading the layout profile --&gt;
                  &lt;layout-base uri="cocoon://financeresource-layoutprofile"/&gt;
                  &lt;!-- The resource for loading the base sunlets profile --&gt;
                  &lt;sunlet-base uri="cocoon://financeresource-sunletprofile"/&gt;
                  &lt;!-- The optional resource for saving the base sunlets profile --&gt;
                  &lt;sunlet-base-save uri="cocoon://financeresource-savesunletprofile"/&gt;
  
                  &lt;!-- The optional type resource --&gt;
                  &lt;type-base uri="cocoon://financeresource-types"/&gt;
                                       &lt;!-- The optional type resource for the admin configuration --&gt;
                  &lt;admin-type-base uri="cocoon://financeresource-admintypes"/&gt;
  
                  &lt;!-- The resources for loading/saving the deltas --&gt;
                  &lt;global-delta-load uri="cocoon://financeresource-globalprofile"/&gt;
                  &lt;global-delta-save uri="cocoon://financeresource-saveglobalprofile"/&gt;
                  &lt;role-delta-load uri="cocoon://financeresource-roleprofile"/&gt;
                  &lt;role-delta-save uri="cocoon://financeresource-saveroleprofile"/&gt;
                  &lt;user-delta-load uri="cocoon://financeresource-userprofile"/&gt;
                  &lt;user-delta-save uri="cocoon://financeresource-saveuserprofile"/&gt;
  
                  &lt;!-- Optional resources for loading/saving the status profile
                       which is required for persistent, customizable sunLets --&gt;
                  &lt;user-status-load uri="cocoon://financeresource-loadstatusprofile"/&gt;
                  &lt;user-status-save uri="cocoon://financeresource-savestatusprofile"/&gt;
  
                  &lt;!-- optional type resources --&gt;
                  &lt;global-type-delta uri="..."/&gt;
                  &lt;role-type-delta uri="..."/&gt;
                  &lt;user-type-delta uri="..."/&gt;
              &lt;/profile&gt;
              &lt;!-- Redirect to this resource, if the user is not authenticated
                   to view that sunLet --&gt;
              &lt;auth-redirect&gt;finance-portal&lt;/auth-redirect&gt;
          &lt;/configuration&gt;
      &lt;/application&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Global Portal Configuration</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">One mandatory configuration value for the portal is the
            <i>portal-uri</i>. It must point to a pipeline which produces the portal view
            for a user (see next section for more information about the pipelines).</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Profile Caching</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">sunSpot contains an intelligent profile caching mechanism which
            detects automatically changes to profiles and determines upon this information
            which profile must be rebuild. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Without profile caching a profile is build each time a user logs
            in. With profile caching the profile is only build if there is no cached
            profile or if something has changed in the profiles for this user. Only the
            user status profile is not cached at all as it is often changing.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">By specifying the <i>profile-cache</i> tag in the sunSpot
            configuration with the value <i>true</i> the profile caching is turned on. If
            the tag is not available no profile caching is performed.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If profile caching is turned on, the profiles should not be changed
            by hand as the cache does not detect such changes. All changes to the profiles
            must be done using the sunSpot tools. However if you change a profile or part
            of a profile by hand, make sure that you clean the cache afterwords. Cleaning
            the cache can be done either by the provided sunSpot tools or by deleting all
            files inside the cache directory.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Global sunLet configuration</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Usually the portal view is generated step by step, e.g. the sunLets
            are build one after the other. sunSpot can be configured to get the sunLets
            content parallel to decrease the response time for the portal view. By
            specifying the <i>process-sunlets-parallel</i> tag with the value
            <i>true</i>, the sunLets are processed parallel.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">If the content of a sunLet is not available, e.g. if the
            contentresides on an external HTTP server, the processing of this sunLet can
            take a "very long" time, e.g. until a timeout occures. sunSpot monitors the
            sunLets and can stop the processing of a sunLet after a distinct period of
            time. This period can be specified by the tag "default-sunlet-timeout" in
            milliseconds. If the content of the sunLet is not available after the time has
            expired, the sunLet is declared as "not available". The default timeout is 10
            minutes.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For a fine-tuning of sunLet timeouts, each sunLet can get its own
            timeout (see the sections below).</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Profile Resources</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each part of the profile has a corresponding resource which is
            invoked for loading or saving the profile part, e.g. one resource for loading
            the global profile delta and a separate one for saving it. The loading
            resources must deliver the xml described in the previous chapters. </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">All resources get the parameter "application" with the name of the
            corresponding application and "handler" with the name of the sunRise handler.
            The list below shows the additional parameters for the other resources.</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">sunlet-base: "profile" with value "sunlet-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">sunlet-base-save: "profile" with value "sunlet-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">layout-base: "profile" with value "layout-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">type-base: "profile" with value "type-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">admin-type-base: "profile" with value "admin-type-base"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">global-delta-load: "profile" with value "global-delta"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">global-type-delta: "profile" with value "global-type-delta"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">global-delta-save: "profile" with value "global-delta"
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">role-delta-load: "profile" with value "role-delta", "role"
               with name of the role
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">role-delta-save: "profile" with value "role-delta", "role"
               with name of the role
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">role-type-delta: "profile" with value "role-type-delta",
               "role" with role name
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-delta-load: "profile" with value "user-delta", "role"
               with role name, "ID" with user ID
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-delta-save: "profile" with value "user-delta", "role"
               with role name, "ID" with user ID
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-type-delta: "profile" with value "user-type-delta",
               "role" with role name, "ID" with user ID
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-status-load: "profile" with value "user-status", "role"
               with role name, "ID" with the user ID
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">user-status-save: "profile" with value "user-status", "role"
               with role name, "ID" with the user ID
            </font>
  </li>
          
  </ul>
  </blockquote>
       
    
    
  <font face="verdana, helvetica, sans serif" size="+2" color="#0086b2">The Pipelines</font>
  <hr style="color: #0086b2" size="1">
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">So far the chapters only described configuring sunSpot and writing
          resources. This chapter closes the gap and explains the steps for showing the
          portal.</font>
  </p>
       
  <p>
  <font color="black" face="verdana,helvetica,sanserif">For defining the pipelines in the sitemap, sunSpot declares two
          generators (the "sunSpotGenerator" and the "sunSpotConfGenerator") and one
          transformer ("sunSpot").</font>
  </p>
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Displaying the portal view</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Displaying the portal view is a very simple step: defining a
            pipeline with the "sunSpotGenerator" as the generator, the sunRise transformer
            for defining the application and an stylesheet for creating the presentation:
            </font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>		&lt;map:match pattern="sunbank-portal"&gt;
                  &lt;map:act type="sunRise-auth"/&gt;         &lt;!-- for getting the sunSpot configuration --&gt;
                          &lt;map:parameter name="handler" value="sunshinehandler"/&gt;
                           &lt;map:parameter name="application" value="sunBank"/&gt;
  
                      &lt;map:generate type="sunSpot"/&gt; &lt;!-- generate the portal view --&gt;
                              &lt;map:transform src="sunbank/styles/portalHTML.xsl"/&gt; &lt;!-- presentation in HTML --&gt;
                        &lt;map:serialize/&gt;
        &lt;/map:act&gt;
          &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The Generated Portal View</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The XML generated by the "sunSpotGenerator" is not exactly the
               same as for the user profile. sunSpot optimizes and reorganizes the profile.
               All fields (or nodes) which are changeable have the attributes
               "formdescription", "formpath" and "formtype". "formdescription" is a user
               readable description of the field, "formpath" is the name of the form parameter
               which can be used to set the value and "formtype" indicates the type of the
               field. The belonging type can be found in the types section of the
               profile.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;!-- The portal indicates that the following is the portal view --&gt;
  &lt;portal&gt;
  
      &lt;!-- The configuration of the portal --&gt;
      &lt;configuration&gt;
          &lt;!-- This is the uri which should be invoked for rebuilding the portal view
               and for changing the view. The parameter sunspotprofile is always
               present and indicates the current profile. --&gt;
          &lt;uri&gt;finance-portlets?sunspotprofile=uprofile:sunBank:user_admin_sunshine&lt;/uri&gt;
          &lt;!-- This is the uniquie sunSpot profile ID --&gt;
          &lt;profile&gt;uprofile:sunBank:user_admin_sunshine&lt;/profile&gt;
          &lt;media&gt;html&lt;/media&gt; &lt;!-- The current media: html or wap --&gt;
      &lt;/configuration&gt;
  
      &lt;!-- Now the needed part of the layout profile: --&gt;
      &lt;layout&gt;
          &lt;portal&gt;
                          &lt;background&gt;
                                  &lt;color formdescription="Hintergrundfarbe" formpath="sunspotconf.0.0" formtype="backgroundcolor"&gt;#aab9bf&lt;/color&gt;
                          &lt;/background&gt;
                          &lt;font&gt;
                                  &lt;type&gt;Arial, Helvetica, sans-serif&lt;/type&gt;
                                  &lt;size&gt;2&lt;/size&gt;
                                  &lt;color formdescription="Schriftfarbe" formpath="sunspotconf.1.0" formtype="textcolor"&gt;black&lt;/color&gt;
                          &lt;/font&gt;
                      &lt;/portal&gt;
  
          &lt;sunlets&gt;
                             &lt;title&gt;
                                  &lt;background&gt;
                                        &lt;color&gt;#46627A&lt;/color&gt;
                                  &lt;/background&gt;
                                    &lt;font&gt;
                                      &lt;type&gt;Arial&lt;/type&gt;
                                         &lt;size&gt;2&lt;/size&gt;
                                         &lt;color&gt;#ffffff&lt;/color&gt;
                                    &lt;/font&gt;
                             &lt;/title&gt;
                          &lt;content&gt;
                                  &lt;background&gt;
                                        &lt;color&gt;#000000&lt;/color&gt;
                                  &lt;/background&gt;
                                    &lt;font&gt;
                                      &lt;type&gt;Arial&lt;/type&gt;
                                         &lt;size&gt;2&lt;/size&gt;
                                         &lt;color&gt;#ffffff&lt;/color&gt;
                                    &lt;/font&gt;
                             &lt;/content&gt;
                      &lt;/sunlets&gt;
      &lt;/layout&gt;
  
      &lt;!-- This is the portal view: --&gt;
      &lt;header&gt;
          &lt;sunlet id="personalize" position="1" number="1"&gt;
              &lt;resource uri="financesunlet-personalize.xml"/&gt;
              &lt;configuration&gt;
                              &lt;mandatory&gt;true&lt;/mandatory&gt;
                              &lt;sizable&gt;true&lt;/sizable&gt;
                              &lt;active&gt;true&lt;/active&gt;
                          &lt;/configuration&gt;
              &lt;title&gt;Personalisieren&lt;/title&gt;
              &lt;status&gt;
                  &lt;visible&gt;true&lt;/visible&gt;
                  &lt;size&gt;max&lt;/size&gt;
              &lt;/status&gt;
              &lt;content&gt;..the sunLet content...&lt;/content&gt;
          &lt;/sunlet&gt;
            &lt;/header&gt;
  
      &lt;columns number="3"&gt;
          &lt;column position="1" width="28%"&gt;
                          &lt;sunlet id="administration" position="1" number="1"&gt;
                    &lt;resource uri="financesunlet-administration.xml"/&gt;
                    &lt;configuration&gt;
                        &lt;mandatory&gt;false&lt;/mandatory&gt;
                        &lt;sizable&gt;true&lt;/sizable&gt;
                        &lt;active&gt;true&lt;/active&gt;
                              &lt;/configuration&gt;
                    &lt;title&gt;sunShine Administration&lt;/title&gt;
                    &lt;status&gt;
                        &lt;visible formdescription="Sichtbar" formpath="sunspotconf.4.0" formtype="BOOLEAN"&gt;true&lt;/visible&gt;
                        &lt;size formdescription="Groesse" formpath="sunspotconf.5.0" formtype="sunletsize"&gt;max&lt;/size&gt;
                    &lt;/status&gt;
                    &lt;content&gt;..the sunLet content...&lt;/content&gt;
                &lt;/sunlet&gt;
                          ....
                   &lt;/column&gt;
          &lt;column position="2" width="50%"&gt;
              ...
              &lt;/column&gt;
          &lt;column position="3" width="22%"&gt;
              ...
                   &lt;/column&gt;
      &lt;/columns&gt;
  
      &lt;!-- The personal information --&gt;
      &lt;personal-profile&gt;
          &lt;greeting&gt;Hi there!&lt;/greeting&gt;
          &lt;messages&gt;
                  &lt;sunlet_not_available&gt;The sunLet is currently not available.&lt;/sunlet_not_available&gt;
          &lt;/messages&gt;
      &lt;/personal-profile&gt;
  &lt;/portal&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Administration of the portal view</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Displaying the administration page of the portal is as simple as
            displaying the portal. The difference lies in changing the generator to the
            "sunSpotConfGenerator": </font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>		&lt;map:match pattern="sunbank-conf"&gt;
                    &lt;map:act type="sunRise-auth"&gt;
                           &lt;map:parameter name="handler" value="sunshinehandler"/&gt;
                           &lt;map:parameter name="application" value="sunBank"/&gt;
  
                      &lt;map:generate type="sunSpot-conf"/&gt;
                        &lt;map:transform src="sunbank/styles/portalconfHTML.xsl"/&gt;
                        &lt;map:serialize/&gt;
                    &lt;/map:act&gt;
          &lt;/map:match&gt;
  </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Make sure to protect the portal configuration generator as the
            administrator can change all profiles, clear the cache etc. It should only be
            available for real sunSpot administrators.</font>
  </p>
          
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2">The Generated Administration View</font>
            
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The XML generated by the "sunSpotConfGenerator" is not exactly
               the same as the user profile. sunSpot addes some information to the profile.
               All fields (or nodes) which are changeable have the attributes
               "formdescription", "formpath" and "formtype". "formdescription" is a user
               readable description of the field, "formpath" is the name of the form parameter
               which can be used to set the value and "formtype" indicates the type of the
               field. The belonging type can be found in the types section of the
               profile.</font>
  </p>
            
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;!-- The portalconf node indicates that the following is the portal administration view --&gt;
  &lt;portalconf&gt;
  
  &lt;!-- The configuration of the portal --&gt;
      &lt;configuration&gt;
          &lt;!-- This is the uri which should be invoked for rebuilding the portal view
               and for changing the view. The parameter sunspotprofile is always
               present and indicates the current profile. --&gt;
          &lt;uri&gt;finance-portlets?sunspotprofile=uprofile:sunBank:user_admin_sunshine&lt;/uri&gt;
          &lt;!-- This is the uniquie sunSpot profile ID --&gt;
          &lt;profile&gt;uprofile:sunBank:user_admin_sunshine&lt;/profile&gt;
          &lt;media&gt;html&lt;/media&gt; &lt;!-- The current media: html or wap --&gt;
      &lt;/configuration&gt;
  
      &lt;!-- The layout profile, see chapter about the layout profile --&gt;
      &lt;layout-profile&gt;
              &lt;portal&gt;
                       &lt;layouts&gt;
                           &lt;layout&gt;
                                     &lt;background&gt;
                                          &lt;color formdescription="Hintergrundfarbe" formpath="sunspotconf.0.0" formtype="backgroundcolor"&gt;#aab9bf&lt;/color&gt;
                                     &lt;/background&gt;
                                     &lt;font&gt;
                                          &lt;type&gt;Arial, Helvetica, sans-serif&lt;/type&gt;
                                          &lt;size&gt;2&lt;/size&gt;
                                          &lt;color formdescription="Schriftfarbe" formpath="sunspotconf.1.0" formtype="textcolor"&gt;black&lt;/color&gt;
                                     &lt;/font&gt;
                             &lt;/layout&gt;
                     &lt;/layouts&gt;
  
                     &lt;header&gt;
                              &lt;exists&gt;true&lt;/exists&gt;
                      &lt;/header&gt;
  
                       &lt;columns&gt;
                              &lt;number formdescription="Anzahl" formpath="sunspotconf.2.0" formtype="columnnumber"&gt;3&lt;/number&gt;
                       &lt;/columns&gt;
  
                      &lt;footer&gt;
                              &lt;exists&gt;false&lt;/exists&gt;
                      &lt;/footer&gt;
                &lt;/portal&gt;
  
                &lt;sunlets&gt;
                       &lt;layouts&gt;
                              &lt;layout&gt;
                                  &lt;title&gt;
                                            &lt;background&gt;
                                                &lt;color&gt;#46627A&lt;/color&gt;
                                          &lt;/background&gt;
                                          &lt;font&gt;
                                                 &lt;type&gt;Arial&lt;/type&gt;
                                                  &lt;size&gt;2&lt;/size&gt;
                                              &lt;color&gt;#ffffff&lt;/color&gt;
                                          &lt;/font&gt;
                                  &lt;/title&gt;
                                  &lt;content&gt;
                                          &lt;font&gt;
                                                 &lt;type&gt;Arial&lt;/type&gt;
                                                  &lt;size&gt;2&lt;/size&gt;
                                              &lt;color&gt;#000000&lt;/color&gt;
                                          &lt;/font&gt;
                                            &lt;background&gt;
                                                &lt;color&gt;#ffffff&lt;/color&gt;
                                          &lt;/background&gt;
                                  &lt;/content&gt;
                              &lt;/layout&gt;
                      &lt;/layouts&gt;
              &lt;/sunlets&gt;
  
          &lt;/layout-profile&gt;
  
       &lt;!-- The sunLets profile, see chapter about the sunLets profile --&gt;
       &lt;sunlets-profile&gt;
                &lt;sunlets&gt;
               &lt;sunlet id="banknews"&gt;
                               &lt;resource uri="onlinesunlet-banking.xml"/&gt;
                              &lt;configuration&gt;
                                      &lt;mandatory&gt;false&lt;/mandatory&gt;
                                  &lt;sizable&gt;true&lt;/sizable&gt;
                                      &lt;active&gt;true&lt;/active&gt;
                               &lt;/configuration&gt;
                              &lt;title&gt;Banking News&lt;/title&gt;
                               &lt;status&gt;
                                  &lt;visible&gt;true&lt;/visible&gt;
                                  &lt;size&gt;max&lt;/size&gt;
                              &lt;/status&gt;
                      &lt;/sunlet&gt;
               ...
              &lt;/sunlets&gt;
  
          &lt;/sunlets-profile&gt;
  
       &lt;!-- The type profile, see the chapter about the type profile --&gt;
       &lt;typedefs&gt;
           ...
       &lt;/typedefs&gt;
  
        &lt;!-- And now the portal view, see chapter about the portal profile --&gt;
       &lt;portal-profile&gt;
  
              &lt;content&gt;
                     &lt;header&gt;
                             &lt;sunlet id="personalize" position="1" number="1"&gt;
                                    &lt;status&gt;
                                             &lt;visible&gt;true&lt;/visible&gt;
                                             &lt;size&gt;max&lt;/size&gt;
                                      &lt;/status&gt;
                               &lt;/sunlet&gt;
                  &lt;/header&gt;
                  &lt;column position="1"&gt;
                          &lt;width formdescription="Breite" formpath="sunspotconf.3.0" formtype="CARDINAL"&gt;28%&lt;/width&gt;
                          &lt;sunlets&gt;
                                 &lt;sunlet id="administration" position="1" number="2"&gt;
                                          &lt;status&gt;
                                              &lt;visible formdescription="Sichtbar" formpath="sunspotconf.4.0" formtype="BOOLEAN"&gt;true&lt;/visible&gt;
                                              &lt;size formdescription="Groesse" formpath="sunspotconf.5.0" formtype="sunletsize"&gt;max&lt;/size&gt;
                                          &lt;/status&gt;
                                  &lt;/sunlet&gt;
                                 ...
                          &lt;/sunlets&gt;
                     &lt;/column&gt;
  
                      &lt;column position="2"&gt;
                     ...
                      &lt;/column&gt;
  
                      &lt;column position="3"&gt;
                     ...
                      &lt;/column&gt;
  
              &lt;/content&gt;
       &lt;/portal-profile&gt;
  
       &lt;!-- The personal profile, see the corresponding chapter --&gt;
       &lt;personal-profile&gt;
              &lt;greeting&gt;Hi there!&lt;/greeting&gt;
              &lt;messages&gt;
                  &lt;sunlet_not_available&gt;The sunLet is currently not available.&lt;/sunlet_not_available&gt;
              &lt;/messages&gt;
       &lt;/personal-profile&gt;
  &lt;/portalconf&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Changing the Profile</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The profile can be changed using a HTTP request. The invoked
            resources is the uri defined in the "configuration" section of the portal view.
            It contains already the needed parameter "sunspotprofile" with the given value.
            This parameter tells sunSpot which profile it should change.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif"> Each field which is changeable has the parameters
            "formdescription", "formtype" and "formpath". The "formdescription" is a
            user-readable text for this field. The "formtype" is the type of the field. It
            is a type name which has a corresponding entry in the type profile. The type
            profile contains all possible values for this particular type. The "formpath"
            contains the name of the field to change. So changing an field is submitting a
            form value with the name of "formpath" and one of the values denoted by the
            "formtype". </font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In addition to this sunSpot recognizes the special parameter
            "sunspotcmd". It can control the appearance of the sunLets. The value of the
            parameter is one of the following followed by '_', the sunLet id attribute,
            another '_' and the sunLet number attribute. For example minimizing a sunLet is
            done by passing "sunspotcmd=minimize_1_3" to the request. The commands are as
            follows:</font>
  </p>
          
  <blockquote>
  <ul>
            
  <li>
  <font face="verdana, helvetica, sans serif">"maximize" : Maximize the sunLet.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"minimize" : Minimize the sunLet.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"close" or "hide" : Close the sunLet, it will not be
               displayed in the portal view, but is still configured.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"open" or "show" : A configured sunLet will be included in
               the portal view again.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"delete" : Remove the sunLet from the profile.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"move" : Move the sunLet to the column which is append to
               value separated by '_'. So "sunspotcmd=move_1_3_2" would move the sunLet into
               the 2nd column.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"new" : Add a new sunLet to the profile. Only the attribute
               id of the sunLet is passed. Instead of the number attribute the column number
               is appended. If instead "header" or "footer" is passed instead of the column
               number, the sunLet is moved into that special area.
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">"update" : Change from the customization view of the sunLet
               to the sunLet content view.
            </font>
  </li>
          
  </ul>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The profile can be save persistent by sending the parameter
            "sunspotcmd" with the value "save"in addition to the "sunspotprofile"
            parameter.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Defining sunLets</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Defining a pipeline for a sunLet is also very straightforward.
            Together with your "real" pipeline for defining the content and doing the
            presentation, the "sunSpot-auth" action and the sunRise-auth action are needed.
            The first one for protecting the sunLet and the second one for defining the
            application the resource belongs to:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>		&lt;map:match pattern="licence-sunlet"&gt;
        &lt;!-- Get the application configuration --&gt;
                    &lt;map:act type="sunRise-auth"&gt;
                           &lt;map:parameter name="handler" value="sunshinehandler"/&gt;
                           &lt;map:parameter name="application" value="sunBank"/&gt;
  
            &lt;!-- secure the sunLet: --&gt;
            &lt;map:act type="sunSpot-auth"&gt;
                 &lt;map:parameter name="sunLet" value="licencing"/&gt;
            &lt;/map:act&gt;
  
                  &lt;!-- The resource containg the licencing information: --&gt;
            &lt;map:generate src="sunshine/licencing.xml"/&gt;
  
            &lt;!-- present it in HTML --&gt;
                        &lt;map:transform src="sunbank/styles/HTML.xsl"/&gt;
            &lt;!-- Serialize it to XML for including in the portal view: --&gt;
                        &lt;map:serialize/&gt;
        &lt;/map:act&gt;
          &lt;/map:match&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">In this example the sunLet is protected by the use of the parameter
            tag inside the "sunSpot-auth" action. Only if the user is allowed to
            view/configure the sunLet with the ID "licencing", he can invoke this resource.
            If this security command is left out, everyone is able to get the resource by
            simply invoking it directly from the browser. However, if the sunLet is
            protected it is not necessary that a user has choosen that sunLet for his
            current portal view to invoke the resource. In addition it is possible to
            specify the parameter without a specific sunlet name. This protects the
            resource as a sunLet: Only users which are logged in to the portal can view the
            resource.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Getting Profile Information within a sunLet</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each sunLet has access to nearly all information of the profile,
            including layout information and configuration. The sunLet can retrieve this
            information using a special session context called <i>sunSpot</i>. With the
            familiar commands of the <i>sunShine</i> transformer (<i>getxml</i> etc.)
            the information can be included in the current xml stream of a sunLet.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The content of the context looks like the following:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;layout&gt;
      &lt;portal&gt;
                  &lt;background&gt;
                              &lt;color formdescription="Hintergrundfarbe" formpath="sunspotconf.0.0" formtype="backgroundcolor"&gt;#aab9bf&lt;/color&gt;
                  &lt;/background&gt;
                  &lt;font&gt;
                              &lt;type&gt;Arial, Helvetica, sans-serif&lt;/type&gt;
                              &lt;size&gt;2&lt;/size&gt;
                              &lt;color formdescription="Schriftfarbe" formpath="sunspotconf.1.0" formtype="textcolor"&gt;black&lt;/color&gt;
                       &lt;/font&gt;
      &lt;/portal&gt;
  
      &lt;sunlets&gt;
                      &lt;title&gt;
                              &lt;background&gt;
                              &lt;color&gt;#46627A&lt;/color&gt;
                              &lt;/background&gt;
                          &lt;font&gt;
                                  &lt;type&gt;Arial&lt;/type&gt;
                                     &lt;size&gt;2&lt;/size&gt;
                                     &lt;color&gt;#ffffff&lt;/color&gt;
                          &lt;/font&gt;
                      &lt;/title&gt;
                      &lt;content&gt;
                              &lt;background&gt;
                              &lt;color&gt;#000000&lt;/color&gt;
                              &lt;/background&gt;
                          &lt;font&gt;
                                  &lt;type&gt;Arial&lt;/type&gt;
                                     &lt;size&gt;2&lt;/size&gt;
                                     &lt;color&gt;#ffffff&lt;/color&gt;
                          &lt;/font&gt;
                      &lt;/content&gt;
                  &lt;/sunlets&gt;
  &lt;/layout&gt;
  &lt;configuration&gt;
          &lt;!-- This is the uri which should be invoked for rebuilding the portal view
               The parameter sunspotprofile is always
               present and indicates the current profile. --&gt;
          &lt;uri&gt;finance-portlets?sunspotprofile=uprofile:sunBank:user_admin_sunshine&lt;/uri&gt;
          &lt;!-- This is the uniquie sunSpot profile ID --&gt;
          &lt;profile&gt;uprofile:sunBank:user_admin_sunshine&lt;/profile&gt;
          &lt;media&gt;html&lt;/media&gt; &lt;!-- The current media: html or wap --&gt;
  &lt;/configuration&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using this information the sunLet can layout itself with the layout
            chosen by the user for the portal. For example a <i>&lt;sunshine:getxml
            context="sunSpot" path="/layout/sunlets/content/background/color"/&gt;</i> is
            replaced by the sunShine transformer with the color value for the background
            (here "#000000)".</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>Writing Customizable sunLets</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Writing a customizable sunLet requires two task:</font>
  </p>
          
  <blockquote>
  <ol>
            
  <li>
  <font face="verdana, helvetica, sans serif">Creating the resource for the customization of the sunLet
            </font>
  </li>
            
  <li>
  <font face="verdana, helvetica, sans serif">Creating a resource for the sunLet content which uses the
               configuration
            </font>
  </li>
          
  </ol>
  </blockquote>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The resource for the customization is very similar to the "real"
            resource for the sunLet. It is - in most cases - a pipeline which delivers xml
            and this xml is included in the portal view. Usually this xml contains a form
            for the user to define the configuration of the sunLet.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The configuration of the sunLet is available using the special
            <i>sunSpot</i> session context. For a customizable sunLet this context is
            augmented with the current configuration of the sunLet:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;layout&gt;
      ...
  &lt;/layout&gt;
  &lt;configuration&gt;
      ...
      &lt;context&gt;unique id for the sunLet for external applications&lt;/context&gt;
  &lt;/configuration&gt;
  &lt;sunlet-data&gt;
      ... the configuration ....
  &lt;/sunlet-data&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Using the sunShine form handling it is very easy to write a
            customization view for a sunLet. The following example dispalys a form for a
            mail sunLet which requires the configuration for a mail host, a user name and a
            password.</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:sunshine="http://cocoon.apache.org/sunshine/1.0"&gt;
         &lt;!-- Define a form --&gt;
      &lt;sunshine:form name="popmail" method="POST"&gt;
              &lt;sunshine:action&gt;
              &lt;!-- The action is send to the pipeline redisplaying the portal --&gt;
              &lt;sunshine:getxml context="sunSpot" path="/configuration/uri"/&gt;
          &lt;/sunshine:action&gt;
          &lt;!-- Create the input fields for
               host, username and password --&gt;
              &lt;sunshine:content&gt;
                       &lt;sunshine:inputxml context="sunSpot" path="/sunlet-data/host" name="Host" type="text"/&gt;
                       &lt;sunshine:inputxml context="sunSpot" path="/sunlet-data/user" name="User" type="text"/&gt;
                       &lt;sunshine:inputxml context="sunSpot" path="/sunlet-data/password" name="Password" type="password"/&gt;
              &lt;/sunshine:content&gt;
          &lt;!-- The submit button --&gt;
          &lt;input type="submit" value="Customize"/&gt;
      &lt;/sunshine:form&gt;
  &lt;/page&gt;
          </pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The sunShine <i>inputxml</i> tags assure that the information
            provided by the user is automatically written into the <i>sunSpot</i> context
            at the places provided.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Writing the resource for the sunLet is as easy. The sunLet can use
            the <i>getxml</i> command to retrieve to configuration from the
            <i>sunSpot</i> context:</font>
  </p>
          
  <div align="center">
  <table border="0" cellpadding="0" cellspacing="4">
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td bgcolor="#ffffff">
  <pre>&lt;page xmlns:sunshine="http://cocoon.apache.org/sunshine/1.0"&gt;
      &lt;!-- Get the configuration information out of the sunSpot context --&gt;
      &lt;!-- and feed it into the getmail command --&gt;
          &lt;sunshine:getmail&gt;
              &lt;sunshine:user&gt; &lt;!-- Set the user --&gt;
               &lt;sunshine:getxml path="/sunlet-data/user" context="sunSpot"/&gt;
           &lt;/sunshine:user&gt;
              &lt;sunshine:password&gt; &lt;!-- Set the password --&gt;
               &lt;sunshine:getxml path="/sunlet-data/password" context="sunSpot"/&gt;
           &lt;/sunshine:password&gt;
              &lt;sunshine:host&gt; &lt;!-- Seet the host --&gt;
               &lt;sunshine:getxml path="/sunlet-data/host" context="sunSpot"/&gt;
           &lt;/sunshine:host&gt;
          &lt;/sunshine:getmail&gt;
  &lt;/page&gt;</pre>
  </td><td width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  <tr>
  <td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td><td height="1" width="1" bgcolor="#0086b2"><img border="0" hspace="0" vspace="0" height="1" width="1" src="images/void.gif"></td>
  </tr>
  </table>
  </div>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">Each time the sunLet configuration changes the user status profile
            is automatically saved.</font>
  </p>
       
       
  <font face="verdana, helvetica, sans serif" size="+1" color="#0086b2"><b>External Resources and Customizable sunLets</b></font>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">External resources which are configured with the same sunRise
            handler and application as the portal can retrieve configuration information
            from a sunLet. If the resource is invoked with the request parameter
            <i>sunspotcontext</i> it has access to the same sunSpot context as the
            sunLet.</font>
  </p>
          
  <p>
  <font color="black" face="verdana,helvetica,sanserif">The value for the request parameter can be retrieved by the calling
            resource, e.g. the sunLet, from the <i>sunSpot</i> context using the path
            <i>/configuration/context</i>. The external resource must have the
            <i>sunSpot-auth</i> action configured in its pipeline. The action
            checks for the request parameter and grants the resource access to the
            <i>sunSpot</i> context of the sunLet.</font>
  </p>
       
    
  
  
  </td>
  </tr>
  </table>
  </td>
  </tr>
  </table>
  <table width="100%" cellspacing="0" cellpadding="0" border="0">
  <tr>
  <td bgcolor="#0086b2"><img width="1" src="images/dot.gif" height="1"></td>
  </tr>
  <tr>
  <td align="center"><font size="-1" face="arial,helvetica,sanserif" color="#0086b2"><i>Copyright &copy; 1999-2002 The Apache Software Foundation. All Rights Reserved.</i></font></td>
  </tr>
  </table>
  </body>
  </html>
  
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/bottom.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/button-asf-lo.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/button-w3c-lo.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/button-xml-lo.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/close.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/dot.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/join.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/label-background_a.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/label-background_b.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/line.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/logo.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/note.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/right.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/separator.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-site/targets/cocoon/developing/webapps/images/void.gif
  
  	<<Binary file>>
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: general-cvs-help@xml.apache.org


Mime
View raw message