From seam-commits at lists.jboss.org Thu May 28 23:01:50 2009
Content-Type: multipart/mixed; boundary="===============6181416330280904664=="
MIME-Version: 1.0
From: seam-commits at lists.jboss.org
To: seam-commits at lists.jboss.org
Subject: [seam-commits] Seam SVN: r11029 -
 branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US.
Date: Thu, 28 May 2009 22:51:52 -0400
Message-ID: <E1M9sCG-0000zq-QT@committer01.frg.pub.inap.atl.jboss.com>

--===============6181416330280904664==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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/Conver=
sations.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Conversation=
s.xml	2009-05-29 02:17:32 UTC (rev 11028)
+++ branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Conversation=
s.xml	2009-05-29 02:51:52 UTC (rev 11029)
@@ -432,6 +432,58 @@
         </itemizedlist>
         =

     </section>
+
+    <section id=3D"conversations.required">
+        <title>Requiring a long-running conversation</title>
+        <para>
+            Certain pages are only relevant in the context of a long-runni=
ng conversation. One way to "protect" such a
+            page is to require a long-running conversation as a prerequisi=
te 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>conversa=
tion-required</literal> attribute as follows:
+        </para>
+
+        <programlisting role=3D"XML"><![CDATA[<page view-id=3D"/book.xhtml=
" conversation-required=3D"true"/>]]></programlisting>
+
+        <note>
+           <para>
+               The only downside is there's no built-in way to indicate <e=
mphasis>which</emphasis> long-running
+               conversation is required. You can build on this basic autho=
rization 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.noC=
onversation</literal> is raised</para>
+            </listitem>
+            <listitem>
+                <para>A warning status message is registered using the bun=
dle key <literal>org.jboss.seam.NoConversation</literal></para>
+            </listitem>
+            <listitem>
+                <para>The user is redirected to an alternate page, if defi=
ned</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 desc=
riptor as follows:
+        </para>
+
+        <programlisting role=3D"XML"><![CDATA[<pages no-conversation-view-=
id=3D"/main.xhtml"/>]]></programlisting>
+
+        <para>
+            At the moment, you can only define one such page for the entir=
e 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
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Events.xml	2=
009-05-29 02:17:32 UTC (rev 11028)
+++ branches/community/Seam_2_1/doc/Seam_Reference_Guide/en-US/Events.xml	2=
009-05-29 02:51:52 UTC (rev 11029)
@@ -1207,27 +1207,12 @@
 </exception>]]></programlisting>
 =

             <para>
-                A <literal>ViewExpiredException</literal> occurs if the us=
er posts back
-                to a page once their session has expired.  <literal>no-con=
versation-view-id</literal>
-                and <literal>conversation-required</literal> give you fine=
r grained control over
-                session expiration if you are inside a conversation.
+                A <literal>ViewExpiredException</literal> occurs if the us=
er 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 l=
inkend=3D"conversations.required"/>, give you
+                finer-grained control over session expiration if you are a=
ccessing 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> ele=
ment in <literal>pages.xml</literal>,
-          this setting controls whether a page requires an active long-run=
ning or nested conversation before
-          being rendered.  If there is not an active long-running or neste=
d 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=3D"/foo.xhtml" conversati=
on-required=3D"true"/>]]></programlisting>
-        =

-      </section>
     =

 </chapter>


--===============6181416330280904664==--