[jboss-cvs] jboss-seam/doc/reference/en/modules ...

[Peter Muir]

  User: pmuir   
  Date: 07/08/29 11:46:17

  Modified:    doc/reference/en/modules  events.xml
  Log:
  JBSEAM-1847
  
  Revision  Changes    Path
  1.30      +124 -81   jboss-seam/doc/reference/en/modules/events.xml
  
  (In the diff below, changes in quantity of whitespace are not shown.)
  
  Index: events.xml
  ===================================================================
  RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/events.xml,v
  retrieving revision 1.29
  retrieving revision 1.30
  diff -u -b -r1.29 -r1.30
  --- events.xml	8 Aug 2007 11:37:33 -0000	1.29
  +++ events.xml	29 Aug 2007 15:46:17 -0000	1.30
  @@ -134,6 +134,13 @@
               </para>
               
               <para>
  +                You can use page parameters with or without an action method.
  +            </para>
  +            
  +            <sect4>
  +                <title>Mapping request parameters to the model</title>
  +            
  +              <para>
                   Seam lets us provide a value binding that maps a named request parameter 
                   to an attribute of a model object.
               </para>
  @@ -143,7 +150,7 @@
           <param name="firstName" value="#{person.firstName}"/>
           <param name="lastName" value="#{person.lastName}"/>
       </page>
  -</pages>]]></programlisting>
  +  </pages>]]></programlisting>
   
               <para>
                   The <literal>&lt;param&gt;</literal> declaration is bidirectional, just
  @@ -177,7 +184,7 @@
                   <listitem>
                       <para>
                           The value is transparently propagated with any JSF form submission
  -                        for the page with the given view id. (This means that view parameters
  +                          for the page with the given view id. This means that view parameters
                           behave like <literal>PAGE</literal>-scoped context variables for
                           faces requests.
                       </para>
  @@ -193,6 +200,49 @@
                   state).
               </para>
               
  +            </sect4>
  +            
  +            <sect4>
  +                <title>Propagating request parameters</title>
  +                
  +                <para>
  +                    If just the <literal>name</literal> attribute is specified then the
  +                    request parameter is propagated using the <literal>PAGE</literal> context
  +                    (it isn't mapped to model property).
  +                </para>
  +              
  +          <programlisting><![CDATA[<pages>
  +      <page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
  +          <param name="firstName" />
  +          <param name="lastName" />
  +      </page>
  +  </pages>]]></programlisting>
  +  
  +               <para>
  +                  Propagation of page parameters is especially useful if you want to build multi-layer 
  +                  master-detail CRUD pages.  You can use it to "remember" which view you were previously
  +                  on (e.g. when pressing the Save button), and which entity you were editing.
  +               </para>
  +  
  +               <itemizedlist>
  +                  <listitem>
  +                      <para>
  +                          Any <literal>&lt;s:link&gt;</literal> or <literal>&lt;s:button&gt;</literal> 
  +                          transparently propagates the request parameter if that parameter is listed
  +                          as a page parameter for the view.
  +                      </para>
  +                  </listitem>
  +                  <listitem>
  +                      <para>
  +                          The value is transparently propagated with any JSF form submission
  +                          for the page with the given view id. (This means that view parameters
  +                          behave like <literal>PAGE</literal>-scoped context variables for
  +                          faces requests.
  +                      </para>
  +                  </listitem>
  +              </itemizedlist>
  +            </sect4>
  +            
               <para>
                   This all sounds pretty complex, and you're probably wondering if such an
                   exotic construct is really worth the effort. Actually, the idea is very
  @@ -206,20 +256,11 @@
                   much easier to code.
               </para>
               
  -            <para>
  -                Note that you don't need an actual page action method binding to use
  -                a page parameter. The following is perfectly valid:
  -            </para>
  -            
  -            <programlisting><![CDATA[<pages>
  -    <page view-id="/hello.jsp">
  -        <param name="firstName" value="#{person.firstName}"/>
  -        <param name="lastName" value="#{person.lastName}"/>
  -    </page>
  -</pages>]]></programlisting>
  +            <sect4>
  +                <title>Conversion and Validation</title>
   
               <para>
  -                You can even specify a JSF converter:
  +                You can a JSF converter for complex model propreties:
               </para>
   
               <programlisting><![CDATA[<pages>
  @@ -279,6 +320,8 @@
                   is added to the <literal>FacesContext</literal>.
               </para>
   
  +            </sect4>
  +
           </sect3>
           
           <sect3>