[seam-commits] Seam SVN: r11029 - branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US.

[seam-commits at lists.jboss.org]

Author: dan.j.allen
Date: 2009-05-28 22:51:52 -0400 (Thu, 28 May 2009)
New Revision: 11029

Modified:
   branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Conversations.xml
   branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Events.xml
Log:
JBSEAM-2399


Modified: branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Conversations.xml
===================================================================
--- branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Conversations.xml	2009-05-29 02:17:32 UTC (rev 11028)
+++ branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Conversations.xml	2009-05-29 02:51:52 UTC (rev 11029)
@@ -432,6 +432,58 @@
         </itemizedlist>
         
     </section>
+
+    <section id="conversations.required">
+        <title>Requiring a long-running conversation</title>
+        <para>
+            Certain pages are only relevant in the context of a long-running conversation. One way to "protect" such a
+            page is to require a long-running conversation as a prerequisite to rendering the page. Fortunately, Seam
+            has a built-in mechanism for enforcing this requirement.
+        </para>
+        <para>
+            In the Seam page descriptor, you can indicate that the current conversation must be long-running (or nested)
+            in order for a page to be rendered using the <literal>conversation-required</literal> attribute as follows:
+        </para>
+
+        <programlisting role="XML"><![CDATA[<page view-id="/book.xhtml" conversation-required="true"/>]]></programlisting>
+
+        <note>
+           <para>
+               The only downside is there's no built-in way to indicate <emphasis>which</emphasis> long-running
+               conversation is required. You can build on this basic authorization by dually checking if a specific
+               value is present in the conversation within a page action.
+           </para>
+        </note>
+
+        <para>
+            When Seam determines that this page is requested outside of a long-running conversation, the following
+            actions are taken:
+        </para>
+
+        <itemizedlist>
+            <listitem>
+                <para>A contextual event named <literal>org.jboss.seam.noConversation</literal> is raised</para>
+            </listitem>
+            <listitem>
+                <para>A warning status message is registered using the bundle key <literal>org.jboss.seam.NoConversation</literal></para>
+            </listitem>
+            <listitem>
+                <para>The user is redirected to an alternate page, if defined</para>
+            </listitem>
+        </itemizedlist>
+        
+        <para>
+            The alternate page is defined in the <literal>no-conversation-view-id</literal> attribute on a
+            <literal>&lt;pages&gt;</literal> element in the Seam page descriptor as follows:
+        </para>
+
+        <programlisting role="XML"><![CDATA[<pages no-conversation-view-id="/main.xhtml"/>]]></programlisting>
+
+        <para>
+            At the moment, you can only define one such page for the entire application.
+        </para>
+
+    </section>
     
     <section>
         <title>Using <literal>&lt;s:link&gt;</literal> and <literal>&lt;s:button&gt;</literal></title>

Modified: branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Events.xml
===================================================================
--- branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Events.xml	2009-05-29 02:17:32 UTC (rev 11028)
+++ branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Events.xml	2009-05-29 02:51:52 UTC (rev 11029)
@@ -1207,27 +1207,12 @@
 </exception>]]></programlisting>
 
             <para>
-                A <literal>ViewExpiredException</literal> occurs if the user posts back
-                to a page once their session has expired.  <literal>no-conversation-view-id</literal>
-                and <literal>conversation-required</literal> give you finer grained control over
-                session expiration if you are inside a conversation.
+                A <literal>ViewExpiredException</literal> occurs if the user posts back to a page once their session has
+                expired. The <literal>conversation-required</literal> and <literal>no-conversation-view-id</literal>
+                settings in the Seam page descriptor, discussed in <xref linkend="conversations.required"/>, give you
+                finer-grained control over session expiration if you are accessing a page used within a conversation.
             </para>
         </section>
       </section>
-        
-      <section>
-        <title>conversation-required</title>
-        
-        <para>
-          When specified as the attribute of a <literal>page</literal> element in <literal>pages.xml</literal>,
-          this setting controls whether a page requires an active long-running or nested conversation before
-          being rendered.  If there is not an active long-running or nested conversation when trying to access
-          the page, you will be redirected to the <literal>no-conversation-view-id</literal> view (which is specified 
-          in the root <literal>pages</literal> element) instead.
-        </para>
-        
-        <programlisting><![CDATA[  <page view-id="/foo.xhtml" conversation-required="true"/>]]></programlisting>
-        
-      </section>
     
 </chapter>