[seam-commits] Seam SVN: r8731 - trunk/doc/Seam_Reference_Guide/en-US.

[seam-commits at lists.jboss.org]

Author: norman.richards at jboss.com
Date: 2008-08-18 16:58:19 -0400 (Mon, 18 Aug 2008)
New Revision: 8731

Modified:
   trunk/doc/Seam_Reference_Guide/en-US/Configuration.xml
Log:
JBSEAM-274

Modified: trunk/doc/Seam_Reference_Guide/en-US/Configuration.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Configuration.xml	2008-08-18 19:33:26 UTC (rev 8730)
+++ trunk/doc/Seam_Reference_Guide/en-US/Configuration.xml	2008-08-18 20:58:19 UTC (rev 8731)
@@ -187,7 +187,80 @@
 
                 <programlisting role="XML"><![CDATA[<web:redirect-filter url-pattern="*.seam"/>]]></programlisting>
             </sect3>
+            
+            
+            <sect3>
+                <title>URL rewriting</title>
+                <para> This filter allows Seam to apply URL rewriting for views based on configuration in the 
+                    <literal>pages.xml</literal> file.  This filter is not activate by default, but can be activated
+                    by adding the configuration to <literal>components.xml</literal>: </para>
 
+                <programlisting role="XML"><![CDATA[<web:rewrite-filter />]]></programlisting>
+                
+                <para>
+                    Rewriting occurs based on rewrite patterns found for views in <literal>pages.xml</literal>. 
+                    Seam URL rewriting does both incoming and outgoing URL rewriting based on the same pattern.
+                    Here's a simple pattern:
+                </para>
+                
+                
+                 <programlisting role="XML"><![CDATA[
+<page view-id="/home.xhtml">
+    <rewrite pattern="/home" />
+</page>
+]]></programlisting>
+
+                <para>
+                    In this case, any incoming request for <literal>/home</literal> will be sent to 
+                    <literal>/home.xhtml</literal>.  More interestingly,
+                    any link generated that would normally point to <literal>/home.seam</literal> will 
+                    instead be rewritten as <literal>/home</literal>.  Rewrite patterns only match the portion of the URL 
+                    before the query parameters.  So, <literal>/home.seam?conversationId=13</literal> and 
+                    <literal>/home.seam?color=red</literal>
+                    will both be matched by this rewrite rule.
+                </para>
+
+                <para>
+                    Rewrite rules can take these query paramters into consideration, as shown with the following rules.                  
+                </para>
+                <programlisting role="XML"><![CDATA[
+<page view-id="/home.xhtml">
+    <rewrite pattern="/home/{color}" />
+    <rewrite pattern="/home" />
+</page>
+]]></programlisting>
+                
+                <para>
+                    In this case, an incoming request for <literal>/home/red</literal> will be served as 
+                    if it were a request
+                    for <literal>/home.seam?color=red</literal>.  Similarly, if color is a page parameter an outgoing 
+                    URL that would normally show as <literal>/home.seam?color=blue</literal> would instead 
+                    be output as
+                    <literal>/home/blue</literal>.  Rules are processed in order, so it is important to list
+                    more specific rules before more general rules.
+                </para>
+                
+                <para>Default Seam query parameters can also be mapped using URL rewriting, allowing for another
+                    option for hiding Seam's fingerprints.
+                    In the following example, <literal>/search.seam?conversationId=13</literal> would 
+                     be written as <literal>/search-13</literal>. 
+                </para>
+                                <programlisting role="XML"><![CDATA[
+<page view-id="/search.xhtml">
+    <rewrite pattern="/search-{conversationId}" />
+    <rewrite pattern="/search" />
+</page>
+]]></programlisting>
+                
+                <para>
+                    Seam URL rewriting provides simple, bidirectional rewriting on a per-view basis.  For more
+                    complex rewriting rules that cover non-seam components, Seam applications can continue to
+                    use the org.tuckey URLRewriteFilter or apply rewriting rules at the web server.
+                </para>
+                
+    
+            </sect3>
+
             <sect3>
                 <title>Multipart form submissions</title>
                 <para> This feature is necessary when using the Seam file upload JSF control. It detects multipart form
@@ -337,6 +410,7 @@
 
             </sect3>
 
+            
             <sect3>
                 <title>Adding custom filters</title>
                 <para> Seam can install your filters for you, allowing you to specify <emphasis>where</emphasis> in the