cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cziege...@apache.org
Subject cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/advanced/authentication book.xml authentication.xml preface.xml
Date Sun, 12 Oct 2003 13:16:32 GMT
cziegeler    2003/10/12 06:16:32

  Modified:    src/documentation/xdocs/ctwig ctwig-installing.xml
               src/documentation/xdocs/userdocs book.xml
  Added:       src/documentation/xdocs/developing/portal book.xml index.xml
                        portal-block.xml
               src/documentation/xdocs/userdocs index.xml
               src/documentation/xdocs/developing/webapps index.xml
                        book.xml forms.xml authentication.xml portal.xml
                        contexts.xml session.xml
  Removed:     src/documentation/xdocs/userdocs/advanced/portal
                        portal-fw-block.xml portal-block.xml book.xml
                        index.xml
               src/documentation/xdocs/userdocs/advanced/session forms.xml
                        session.xml preface.xml book.xml contexts.xml
               src/documentation/xdocs/userdocs intro.xml
               src/documentation/xdocs/userdocs/advanced book.xml
                        preface.xml
               src/documentation/xdocs/userdocs/advanced/authentication
                        book.xml authentication.xml preface.xml
  Log:
  Continue rearranging docs to the old places :(
  This will take some time - so please be patient...
  
  Revision  Changes    Path
  1.5       +1 -1      cocoon-2.1/src/documentation/xdocs/ctwig/ctwig-installing.xml
  
  Index: ctwig-installing.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/ctwig/ctwig-installing.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- ctwig-installing.xml	2 Sep 2003 13:17:33 -0000	1.4
  +++ ctwig-installing.xml	12 Oct 2003 13:16:32 -0000	1.5
  @@ -27,7 +27,7 @@
   				<p>The latest distribution for any operating system can be found in the <fork href="http://cocoon.apache.org/mirror.cgi">Cocoon distribution folder</fork>.  This file contains the Cocoon code, samples, documentation and the Java libraries that enable the Cocoon to work such as Xerces and Xalan.  When you have downloaded it then extract it to somewhere.  This path becomes your {COCOON_HOME}.</p>
   			</s2>
   			<s2 title="Basic Configuration">
  -				<p>Follow the instructions on building Cocoon as per the installation guide that comes with Cocoon.  It can also be found <fork href="../userdocs/installation/index.html">here</fork> as well.  Obviously since you have got the ZIP distribution you do not have to do the CVS bit thus you can start at the Building Apache Cocoon 2 section.  Do each of the following steps:</p>
  +				<p>Follow the instructions on building Cocoon as per the installation guide that comes with Cocoon.  It can also be found <fork href="../installation/index.html">here</fork> as well.  Obviously since you have got the ZIP distribution you do not have to do the CVS bit thus you can start at the Building Apache Cocoon 2 section.  Do each of the following steps:</p>
   				<ul>
   					<li>Set JAVA_HOME</li>
   					<li>Create the WAR using
  
  
  
  1.3       +2 -1      cocoon-2.1/src/documentation/xdocs/developing/portal/book.xml
  
  
  
  
  1.9       +20 -402   cocoon-2.1/src/documentation/xdocs/developing/portal/index.xml
  
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/developing/portal/portal-block.xml
  
  Index: portal-block.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
  
  <document> 
    <header> 
      <title>Configuring the Cocoon Portal</title> 
      <authors><person email="jgreenyer@s-und-n.de" name="Joel Greenyer"></person> 
      </authors> 
      <notice>This document is under development.</notice> 
      <abstract>
          This document describes the use and configuration 
          of the (new) cocoon portal block.
      </abstract> 
    </header> 
    <body> 
      <s1 title="Introducing the Cocoon Portal">
        <p>
          This document describes the use and configuration 
          of the (new) cocoon portal that you can find in the "portal" block.
          (Don't mix this with the older portal version that you can
          find in the "portal-fw" block.)
        </p>
        <s2 title="Important parts of the Cocoon Portal">
          <p>
          </p>
        </s2>
        <s2 title="How is a portal page created by Cocoon?">
          <p>
          </p>
        </s2>
        <s2 title="I want to build my own portal! An approach">
          <p>
          </p>
        </s2>
      </s1>
  
      <s1 title="Configuring the Portal contents">
        <s2 title="Configuring Coplets">
          <p>
          </p>
        </s2>
        <s2 title="Configuring the arrangement of the defined Coplets">
          <p>
          </p>
        </s2>
        <s2 title="...">
          <p>
          </p>
        </s2>
      </s1>
  
      <s1 title="Create a new skin for your portal">
          <p>This section will explain the concepts of the portal layout, 
          considering the <code>skins/basic/</code> skin provided with cocoon, 
          and will describe how to create a new skin by extending the 
          existing stylesheets.</p>
          <note>The skin path can be changed in the portal's sitemap. There is 
          a <code>global-variable</code> specifying the path to the skin folder.</note>
            <p>The basic cocoon portal skin    is a nice and simple example how to visualize a portal. 
            There are several elements that allow to customize the look and feel of the portal.
            A portal with the basic skin consists of </p>
            <ul>
                <li>a <em>header</em></li>
                <li>a <em>tab row</em></li>
                <li>a <em>content section</em> containing the coplet windows</li>
                <li>and a <em>footer </em></li>
            </ul>
          <figure alt="Parts of the portal" height="300" src="images/portal-parts.gif" width="400"></figure>    
          <p>The tab row is actually a part of the content section. As well, a tab row can
          be provided to any coplet window.</p>
            <s2 title="The skin&apos;s stylesheets">
                <p>If we take a look at the <code>skins/basic/styles</code> directory, we 
                find a number of stylesheets:
                </p>
                <ul>
                    <li><code>portal-page.xsl</code>: Creates final HTML page</li>
                    <li><code>tab.xsl</code>: layout of the tab row.</li>
                    <li><code>window.xsl</code>: coplet window layout</li>
                    <li><code>column.xsl</code>: layout of a column</li>
                    <li><code>row.xsl</code>: layout of a row</li>
                    <li><code>login-page.xsl</code>: layout of the login page</li>
                </ul>
                <p>The <code>window.xsl</code> stylesheet determines the layout of a
                coplet window. Normally, a coplet window will contain a header row with a
                title and buttons like minimize, close, etc.</p>
                <p>These coplet windows are arranged in rows and columns to create
                the arrangement typical for portals. There can be several rows per column
                and several columns in the content section. So the thinking is a little
                different than in usual HTML tables.</p>
                <p>The content section or content row usually has a tab row located at the top 
                and the coplet windows are arranged below. The layout of the tabs is
                specified in the <code>tab.xsl</code> stylesheet.</p>
                <p>The <code>portal-page.xsl</code> stylesheet encapsulates the content section
                with the tab row and allows to define a page header and a footer.
                This is probably the first stylesheet we want to take a closer look at.
                </p>
                <note>The <code>tab.xsl</code>, <code>column.xsl</code>,
                <code>row.xsl</code> and <code>window.xsl</code> stylesheets
                are used by the portal components directly and won&apos;t be found 
                anywhere in the sitemap. The <code>cocoon.xconf</code>
                defines which stylesheets will be used by the portal.</note>
                </s2>
                <s2 title="The portal-page.xsl">
                    <p>
                        Here is the place to change the design of the header and footer row. 
                        This stylesheet is used to construct the final HTML page, which displays
                        the portal. The code sample here displays the main template match node of the
                        stylesheet.
                    </p>
                          <source>
  <![CDATA[...
  <xsl:template match="/">
  <html>
   <head>
    <link type="text/css" rel="stylesheet" href="page.css"/>
   </head>
   <body>
    <table bgColor="#ffffff" border="0" 
    cellPadding="0" cellSpacing="0" width="100%">
    <tbody> 
  
    <!-- header row -->
    <tr>
    <td colspan="2"> 
     <table border="2" cellPadding="0" cellSpacing="0" width="100%">
      <tbody> 
       <tr> 
        <td colspan="2" noWrap="" height="10" bgcolor="#DDDDDD">
        </td>
       </tr>
       <tr> 
        <td bgcolor="#CCCCCC" height="100" align="center" 
        valign="middle" width="100%">
        <font size="80pt">Cocoon Portal</font>
        </td>
       </tr>
       <tr> 
        <td colspan="2" noWrap="" height="10" bgcolor="#DDDDDD">
        </td>
       </tr>
      </tbody>
     </table>
    </td>
    </tr>
  
    <!-- content/tab row -->
    <tr>
    <td>
     <xsl:apply-templates/>
    </td>
    </tr>
    
    <!-- footer row -->
    <tr>
    <td colspan="2"> 
     <table border="2" cellPadding="0" cellSpacing="0" width="100%">
      <tbody> 
       <tr> 
        <td colspan="2" noWrap="" height="10" bgcolor="#DDDDDD">
         <img height="1" src="sunspotdemoimg-space.gif" width="1"/>
        </td>
       </tr>
       <tr> 
        <td colspan="2" noWrap="" height="30" bgcolor="#CCCCCC">
         <img height="1" src="sunspotdemoimg-space.gif" width="1"/>
        </td>
       </tr>
      </tbody>
     </table>
    </td>
    </tr>
   </tbody>
   </table>
   </body>
  </html>
  </xsl:template>
  ...]]>
              </source>
            </s2>
            <s2 title="The tab.xsl">
                <p>From the <code>portal-page.xsl</code> stylesheet, we will now
                move upwards in the XSL transformation steps and take a look at the
                stylesheet that was processed before, the <code>tab.xsl</code>.</p>
                <p>Again, this source snippet shows the main template match node of the stylesheet:</p>
  <source><![CDATA[...
  <!-- Process a tab  -->
  <xsl:template match="tab-layout">
  <!-- ~~~~~ Begin body table ~~~~~ -->
  <table border="2" cellpadding="0" cellspacing="0" width="100%">
   <!-- ~~~~~ Begin tab row ~~~~~ -->
   <tr>
   <td>
   <table summary="tab bar" border="2" cellpadding="0" 
      cellspacing="0" width="100%">
    <tr vAlign="top">
     <xsl:for-each select="named-item">
      <xsl:choose>
       <xsl:when test="@selected">
       <!-- ~~~~~ begin selected tab ~~~~~ -->
       <td valign="middle" bgcolor="#DDDDDD">
        <b>
         <a href="{@parameter}">
          <font color="#000000">
           <xsl:value-of select="@name"/>
          </font>
         </a>
        </b>
       </td>
       <!-- ~~~~~ end selected tab ~~~~~ -->
      </xsl:when>
      <xsl:otherwise>
       <!-- ~~~~~ begin non selected tab ~~~~~ -->
       <td valign="middle" bgcolor="#CCCCCC" >
        <div class="tab">
         <a href="{@parameter}">
          <xsl:value-of select="@name"/>
         </a>
        </div>
       </td>
       <!-- ~~~~~ end non selected tab ~~~~~ -->
      </xsl:otherwise>
     </xsl:choose>
     </xsl:for-each>
     <!-- ~~~~~ last "blank" tab ~~~~~ -->
      <td width="99%" bgcolor="#CCCCCC" align="right">
      </td>
    </tr>
    </table>
    </td>
    </tr>
    <!-- ~~~~~ End tab row ~~~~~ -->
  
    <!-- ~~~~~ Begin content row ~~~~~ -->
    <tr>
     <td bgcolor="#FFFFFF">
      <xsl:apply-templates/>
     </td>
    </tr>
    <!-- ~~~~~ End content row ~~~~~ -->
  </table>
  </xsl:template>
  ...]]></source>
          <p>The first row that is created here contains the definition of the tabs. 
          The <code>&lt;xsl:choose&gt;</code> element differentiates between the
          currently selected tab and all other tabs. The <code>@selected</code>
          attribute is generated by the portal and can be accessed as shown
          above. As well, the portal provides the tab&apos;s <code>@parameter</code>
          (usually the tab&apos;s link) and <code>@name</code> attributes. </p>
  
          <note>Depending on the configuration of the portal, it is possible
          that tabbed areas are nested inside each other. So be careful how a tab
          row might look in the middle of another content section.</note>
  
          <p>Nice looking tabs can become pretty complex, take a look at the 
          <code>tab.xml</code> stylesheet in the <code>skins/common/</code>
          skin to see another example.</p>
          <p>Below the tabs, another table cell is defined that will be filled 
          with the contents of the tabbed area. This content will have been processed
          by the <code>columns.xsl</code> stylesheet before - and before that by the 
          <code>row.xsl</code> stylesheet.</p>
        </s2>
        <s2 title="The column.xsl and row.xsl">
            <p>The <code>column.xsl</code> and <code>row.xsl</code> stylesheets
            define the look of the tables in which the coplet windows will be placed.
            Usually, nothing exciting happens in these stylesheets. Here is a listing of the
            important parts, just to give a complete overview.
            </p>
            <p>The main template match node of the <code>column.xsl</code> stylesheet:</p>
            <source><![CDATA[...
  <!-- Process a Column  -->
  <xsl:template match="column-layout">
   
     ...
   
   <table border="{$border}" cellSpacing="0" cellpadding="0" 
      width="100%">
    <xsl:if test="@bgcolor">
     <xsl:attribute name="bgcolor">
      <xsl:value-of select="@bgcolor" /> 
     </xsl:attribute>
    </xsl:if>
    <tr vAlign="top">
     <xsl:for-each select="item">
      <td>
       <xsl:if test="@bgcolor">
        <xsl:attribute name="bgcolor">
         <xsl:value-of select="@bgcolor" /> 
        </xsl:attribute>
       </xsl:if>
       <xsl:if test="@width">
        <xsl:attribute name="width">
         <xsl:value-of select="@width" /> 
        </xsl:attribute>
       </xsl:if>
       <xsl:apply-templates />
      </td>
     </xsl:for-each>
    </tr>
   </table>
  </xsl:template>
  ...]]></source>
            <p>The main template match node of the <code>row.xsl</code> stylesheet:</p>
            <source><![CDATA[...
  <!-- Process a row  -->
  <xsl:template match="row-layout">
  
     ...
     
   <table border="{$border}" cellSpacing="10" width="100%">
    <xsl:if test="@bgcolor">
     <xsl:attribute name="bgcolor">
      <xsl:value-of select="@bgcolor" /> 
     </xsl:attribute>
    </xsl:if>
    <xsl:for-each select="item">
     <tr vAlign="top">
      <xsl:if test="@bgcolor">
       <xsl:attribute name="bgcolor">
        <xsl:value-of select="@bgcolor" /> 
       </xsl:attribute>
      </xsl:if>
      <td>
       <xsl:apply-templates />
      </td>
     </tr>
    </xsl:for-each>
   </table>
  </xsl:template>
  ...]]></source>
        </s2>
        <s2 title="The window.xsl">
            <p>The <code>window.xsl</code> stylesheet determines the design of the coplet
            windows and probably takes the most design effort compared to the other stylesheets.
            A coplet window consists of a table header with the window title and a number
            of buttons like close, minimize, maximize etc. The basic skin provides some
            images in the <code>images/</code> subfolder. The rest of the window will
            be filled with the coplet content, depending on the configuration of
            the coplet.</p>
            <p>A slightly more complex example can be found in the 
            <code>skins/common/</code> skin.</p>
            
            <p>The listing below shows the main template match node:</p>
            <source><![CDATA[...
  <xsl:template match="window">
  
     ...
   
  <table border="2" cellSpacing="0" cellpadding="0" width="100%">
   <tr vAlign="top">
    <td bgColor="{$bgColor}" valign="middle">
     <font>
      <xsl:attribute name="color">#ffffff</xsl:attribute>
      <xsl:attribute name="face">Arial</xsl:attribute>
      <xsl:attribute name="size">2</xsl:attribute>    
      <xsl:choose>
       <xsl:when test="@title">
        <b><xsl:value-of select="@title"/></b>
       </xsl:when>
       <xsl:otherwise>
        <b><xsl:value-of select="title"/></b>
       </xsl:otherwise>
      </xsl:choose>    
     </font>
    </td>
    <td align="right" bgColor="{$bgColor}">
     <xsl:if test="fullscreen-uri">
      <a href="{fullscreen-uri}">
       <img src="customize.gif" border="0" alt="Full Screen"/>
      </a>
     </xsl:if>
     <xsl:if test="maxpage-uri">
      <a href="{maxpage-uri}">
       <img src="show.gif" border="0" alt="Max Page"/>
      </a>
     </xsl:if>
     <xsl:if test="maximize-uri">
      <a href="{maximize-uri}">
       <img src="maximize.gif" border="0" alt="Maximize"/>
      </a>
     </xsl:if>
     <xsl:if test="minimize-uri">
      <a href="{minimize-uri}">
       <img src="minimize.gif" border="0" alt="Minimize"/>
      </a>
     </xsl:if>
     <xsl:if test="remove-uri">
      <a href="{remove-uri}">
       <img src="delete.gif" border="0" alt="Delete"/>
      </a>
     </xsl:if>
    </td>
   </tr>
    <tr>
     <td colSpan="2">
      <xsl:apply-templates select="content"/>
     </td>
    </tr>
  </table>
  </xsl:template>
  ...]]></source>
        </s2>
    </s1>
  
      <s1 title="Further topics">
        <p>
        </p>
      </s1>
    </body> 
  </document>
  
  
  1.7       +23 -13    cocoon-2.1/src/documentation/xdocs/userdocs/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/book.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- book.xml	2 Sep 2003 12:03:18 -0000	1.6
  +++ book.xml	12 Oct 2003 13:16:32 -0000	1.7
  @@ -1,26 +1,36 @@
   <?xml version="1.0" encoding="UTF-8"?>
   <!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
   <book software="Apache Cocoon" 
  -      title="Apache Cocoon User Guide" 
  +      title="Apache Cocoon User Documentation" 
         copyright="@year@ The Apache Software Foundation">
   
  -  <menu label="User Guide">
  -    <menu-item label="Intro" href="intro.html"/>
  +  <menu label="Navigation">
  +    <menu-item label="Main" href="../index.html"/>
  +  </menu>
  +
  +  <menu label="User Documentation">
  +    <menu-item label="Concepts" href="concepts/index.html"/>
  +  </menu>
   
  -    <menu-item label="1. Basics" href="user/preface.html"/>
  -    <menu-item label="2. Advanced" href="advanced/preface.html"/>
  -    <menu-item label="3. Configuration" href="config/preface.html"/>
  +  <menu label="Sitemap Components">
  +    <menu-item label="Generators" href="generators/generators.html"/>
  +    <menu-item label="Transformers" href="transformers/transformers.html"/>
  +    <menu-item label="Serializers" href="serializers/serializers.html"/>
  +    <menu-item label="Matchers" href="matchers/matchers.html"/>
  +    <menu-item label="Selectors" href="selectors/selectors.html"/>
  +    <menu-item label="Actions" href="actions/actions.html"/>
  +    <menu-item label="Readers" href="readers/readers.html"/>
     </menu>
     
  -  <menu label="Developer Guide">
  -    <menu-item label="4. Basics" href="developer/preface.html"/>
  +  <menu label="Control Flow">
  +    <menu-item label="Control Flow" href="flow/index.html"/>
     </menu>
     
  -  <menu label="Appendix">
  -    <menu-item label="A. Installation" href="installation/index.html"/>
  -    <menu-item label="B. Components" href="components/index.html"/>
  -    <menu-item label="C. Concepts" href="concepts/index.html"/>
  -    <external label="D. API (Javadoc)" href="../apidocs/index.html"/>
  +  <menu label="XSP">
  +    <menu-item label="XSP" href="xsp/index.html"/>
     </menu>
   
  +  <menu label="Offline Generation">
  +    <menu-item label="Offline Generation" href="offline/index.html"/>
  +  </menu>
   </book>
  
  
  
  1.7       +0 -0      cocoon-2.1/src/documentation/xdocs/userdocs/index.xml
  
  
  
  
  1.3       +25 -11    cocoon-2.1/src/documentation/xdocs/developing/webapps/index.xml
  
  
  
  
  1.4       +6 -8      cocoon-2.1/src/documentation/xdocs/developing/webapps/book.xml
  
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/developing/webapps/forms.xml
  
  Index: forms.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
  <document>
      <header>
          <title>Simple Forms</title>
          <authors>
              <person name="Carsten Ziegeler" email="cziegeler@s-und-n.de"/>
          </authors>
      </header>
      <body>
    <s1 title="Introduction">
       <p>This chapter describes the (simple) form handling approach of
         the session framework.</p>    
       <note>Cocoon provides several approaches for form handling. This
         chapter explains one of them.</note>
    </s1>
    <s1 title="Form Handling">
       <p>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.</p>
       <p>Cocoon supports this two step process, in addition Cocoon offers
          a single step approach.</p>
       <s2 title="The common approach">
          <p>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.</p>
          <p>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 <em>getxml</em>, the values can
            be fetched.</p>
          <p>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:</p>
          <source>&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;</source>
          <p>A stylesheet can transform this into valid html. The action tag
            indicates that the "form-handling-page" should be invoked by submitting the
            values.</p>
          <p>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:</p>
          <source>&lt;page xmlns:session="http://apache.org/cocoon/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;</source>
          <p>As the form values are appended to the request, <em>getxml</em>
            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.</p>
          <p>If you want to write the information in a session context, you must
            wrap the whole xml inside a setxml:</p>
          <source>&lt;page xmlns:session="http://apache.org/cocoon/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;</source>
          <p>The user data is now stored inside the session context "userdata",
            so the context has the following content:</p>
          <source>&lt;user&gt;
    &lt;forename&gt;Walter&lt;/forename&gt;
    &lt;surname&gt;Walterson&lt;/surname&gt;
  &lt;/user&gt;</source>
       </s2>
       <s2 title="The Session Framework approach">
          <p>The previous chapter showed the common approach for handling form
            values. It forces the user to create two resources for a single form
            handling.</p>
          <p>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.</p>
          <p>The example from the previous chapter could look like this:</p>
          <source>&lt;page xmlns:session="http://apache.org/cocoon/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;</source>
          <p>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.</p>
          <p>The <em>inputxml</em> 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:</p>
          <source>&lt;page xmlns:session="http://apache.org/cocoon/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;</source>
          <p>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.</p>
          <p>The Cocoon approach allows a very easy way of form handling where
            the resource which creates the form also handles the form.</p>
          <p>For editing values - if the context already contains information
            about the user - <em>inputxml</em> inserts the current value inside the tag. So
            the xml streamed would after a second run would look like this:</p>
          <source>&lt;page xmlns:session="http://apache.org/cocoon/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;</source>
          <p>Like <em>getxml</em> it is also possible to provide default values
            for the input field, if the context does not contain any information:</p>
          <source>&lt;session:inputxml name="forename" context="userdata" path="/user/forename"&gt;
       Defaultname
  &lt;/session:inputxml&gt;</source>
          <p>But as always there is one drawback with this approach as well, you
             have to put the <em>session-form-manager</em> action somewhere so
             that it is called when the form values are submitted. As this
             action does no harm, it can simply be put as the first action in your
             main sitemap:</p>
          <source>
          &lt;map:act type="session-form-manager"/&gt;
          </source>
       </s2>
    </s1>
  </body>
  </document>
  
  
  
  1.3       +194 -106  cocoon-2.1/src/documentation/xdocs/developing/webapps/authentication.xml
  
  
  
  
  1.4       +0 -0      cocoon-2.1/src/documentation/xdocs/developing/webapps/portal.xml
  
  
  
  
  1.1                  cocoon-2.1/src/documentation/xdocs/developing/webapps/contexts.xml
  
  Index: contexts.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
  <document>
      <header>
          <title>Session Contexts</title>
          <authors>
              <person name="Carsten Ziegeler" email="cziegeler@s-und-n.de"/>
          </authors>
      </header>
      <body>
    <s1 title="Introduction">
       <p>This chapter describes the concept of the session context provided
         by the session framework (session-fw block).</p>    
      <p>The session framework provides the concept of so called (session) contexts.
        A session context is a data storage in the session that can contain
        arbitrary data in XML format.</p>
        <p>You can define your own contexts for your application. For example,
         if you build a web shop, you can create a context called <em>shop</em>
         and store the basket of the user in it.</p>
        <p>The <em>session transformer</em> is the main component used for
         storing and retrieving information from such a context.</p>
       <note>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 and the
          temporary context.</note>
     </s1>
       <s1 title="session Transformer">
          <p>The <em>session transformer</em> 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 pipeline. All tags must be prefixed
            with the session namespace. So the actual tag used in the document will read
            <em>&lt;session:xxxx&gt;</em>. The current namespace URI for the session 
            transformer is <em>"http://apache.org/cocoon/session/1.0"</em>.</p>
       <s2 title="Context-Tags">
          <p>A context is basically an application specific block of XML data in
            the users session. Each context has a unique name.</p>
          <p>The command <em>createcontext</em> is used to create a new context.
            A <em>name</em> 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.</p>
          <p><em>&lt;createcontext name="mycontext"/&gt;</em></p>
          <p>In order to delete a context the command <em>deletecontext</em> is
            provided. Again a <em>name</em> attribute must be provided.</p>
          <p><em>&lt;deletecontext name="mycontext"/&gt;</em></p>
          <p>Once created, XML data can then be stored inside or read from a
            given context.</p>
       </s2>
       <s2 title="Accessing context data">
          <p>The data in a context can be dynamically accessed using the
            following commands.</p>
          <p></p>
          <p><em>getxml</em> allows data to be read out of a context. A
            <em>path</em> attribute describes the source of the data inside the context and
            consists of an XPath expression. All <em>path</em> values must be absolute and
            only nodes and attributes can be accessed. </p>
          <p>An optional default value can also be provided to allow for the
            nonexistence of the requested data.</p>
          <p><em>&lt;getxml context="mycontext"
            path="/User/Name"/&gt;</em></p>
          <p><em>&lt;getxml context="mycontext"
            path="/User/Name"&gt;Matthew&lt;/getxml&gt;</em></p>
          <p>Attributes can also be accessed.</p>
          <p><em>&lt;getxml context="mycontext"
            path="/User/Name/@Age"/&gt;</em></p>
          <p><em></em></p>
          <p>Data can be written into a context using the <em>setxml</em>
            command. It is possible to set values or nodes as the following examples
            show.</p>
          <p><em>&lt;setxml context="mycontext"
            path="/User/Name"/&gt;Carsten&lt;/setxml&gt;</em></p>
          <p><em>&lt;setxml context="mycontext"
            path="/User/"/&gt;&lt;Name&gt;Carsten&lt;/Name&gt;&lt;/setxml&gt;</em></p>
          <p></p>
          <p>Using the <em>setxml</em> 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
            <em>mergexml</em> command.</p>
          <p></p>
          <p>Use the <em>removexml</em> command to remove nodes from the
            context.</p>
          <p><em>&lt;removexml context="mycontext"
            path="/User/"/&gt;</em></p>
          <s3 title="Example">
            <p>The following example shows the use of several commands and in
               particular how the <em>mergexml</em> command can be used to manipulate context
               data.</p>
            <source>&lt;resource xmlns:session="http://apache.org/cocoon/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;</source>
            <p>In the above example, a context for storing data is added. Using
               the <em>setxml</em> command data is then stored into the context. The following
               <em>mergexml</em> 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.</p>
          </s3>
       </s2>
       <s2 title="Reading and writing contexts">
          <p>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.</p>
          <p>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. </p>
          <p>When a context is created, it can get additional save and load URIs
            which are used for loading/saving to/from the context:</p>
          <p><em>&lt;createcontext name="mycontext" load="cocoon://load-from-db"
            save="cocoon://save-to-db"/&gt;</em></p>
          <p>These URIs can then be used inside a document to load data into a
            context:</p>
          <p><em>&lt;loadxml context="mycontext"/&gt;</em></p>
          <p>This example would then load the context data via the resource
            <em>load-from-db</em> which must be defined in the sitemap.</p>
          <p>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.</p>
          <p><em>&lt;loadxml
            context="mycontext"&gt;&lt;user&gt;ben&lt;/user&gt;&lt;/loadxml&gt;</em></p>
  
          <p>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 <em>contextname</em>.</p>
          <p>Writing context data works in the same manner.</p>
          <p><em>&lt;savexml context="mycontext"/&gt;</em></p>
          <p>Both commands can use the optional <em>path</em> attribute:</p>
          <p><em>&lt;loadxml context="mycontext" path="/user"/&gt;</em></p>
          <p><em>&lt;savexml context="mycotnext" path="/user"/&gt;</em></p>
          <p>The first command will read xml from the uri and store it in the
            context under the node <em>user</em>, the second one saves only the xml subtree
            under the node <em>user</em> to the uri. The resource addressed by the uri will
            be passed in addition to the <em>contextname</em> parameter the <em>path</em>
            parameter with the corresponding value. If the <em>path</em> attribute is not
            present the <em>path</em> parameter will get the value <em>"/"</em>.</p>
       </s2>
    </s1>
    <s1 title="Special Contexts">
       <p>Cocoon creates and maintains special contexts that allow the
          applications to access the environment. This allows the read-only access
          to such things as the current request using the same XPath
          commands previously described. These context do not require any session, they
          are always available and change on every request.</p>
       <s2 title="The Request Context - Accessing the Environment, Part One">
          <p>The request context is an XML description of the current
            (HTTP) request. This context is a special read only context that
            can be accessed with the usual commands:</p>
          <p><em>&lt;getxml context="request" path="/parameter"/&gt;</em></p>
  
          <p>For example, if you want to get the value of a parameter with the
            name <em>username</em> you can include the following command in your XML and it
            will be replaced with the value of the parameter:</p>
          <p><em>&lt;getxml context="request"
            path="/parameter/username"/&gt;</em></p>
          <p>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:</p>
          <p><em>&lt;getxml context="request"
            path="/querystring"/&gt;</em></p>
          <p>The result will be a string in the format
            "?param=aaa&amp;...".</p>
          <p>The complete context you can access via these commands has the
            following XML format:</p>
          <source>&lt;parameter&gt;
    &lt;!-- All parameters: parameter names build the elements with the value of the first parameter with
                            this name as text node child --&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 cinclude transformer namespace.
      The generated XML can be used without modification for the
      cinclude:includexml command. --&gt;
    &lt;cinclude:parameters&gt;
      &lt;cinclude:parameter&gt;
        &lt;cinclude:name&gt;1st parameter name&lt;/cinclude:name&gt;
        &lt;cinclude:value&gt;1st parameter value&lt;/cinclude:value&gt;
      &lt;/cinclude:parameter&gt;
               ...
      &lt;cinclude:parameter&gt;
        &lt;cinclude:name&gt;2nd parameter name&lt;/cinclude:name&gt;
        &lt;cinclude:value&gt;2nd parameter value&lt;/cinclude:value&gt;
      &lt;/cinclude:parameter&gt;
    &lt;/cinclude:parameters&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;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;</source>
       </s2>
       <s2 title="The Temporary Context">
          <p>The temporary context with the name <em>temporary</em> 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/deleted when the current response is finished.</p>
          <p>Using the tempory context it is possible to store any XML
            information for processing the current request.</p>
       </s2>
    </s1>
    <s1 title="Session-Context Input Module">
      <p>In addition to the <em>session transformer</em>, the <em>session-context input module</em>
        can be used directly in the sitemap to get information out of a context.</p>
      <p>The information for the input module consists of two parts, the first
        one being the context name and the second one the path inside the
        context. Let's have a look at an example:</p>
      <source>
  &lt;map:generate src="{session-context:request/method}.xml"/&gt;      
      </source>
      <p>
        In the example above, either <em>GET.xml</em> or <em>POST.xml</em> is
        read by the <em>file generator</em>, depending on the value from
        the context <em>request</em> using the xpath <em>method</em>.
      </p>
      </s1>  
  </body>
  </document>
  
  
  
  1.6       +3 -387    cocoon-2.1/src/documentation/xdocs/developing/webapps/session.xml
  
  
  
  

Mime
View raw message