Author: norman.richards(a)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