svn commit: r358356 - /myfaces/forrest/trunk/content/xdocs/tomahawk/extensionsFilter.xml

[mk...@apache.org]

Author: mkienenb
Date: Wed Dec 21 11:34:08 2005
New Revision: 358356

URL: http://svn.apache.org/viewcvs?rev=358356&view=rev
Log:
Updated documentation on extensions filter.
I'd like to remove the section starting with 

Modified:
    myfaces/forrest/trunk/content/xdocs/tomahawk/extensionsFilter.xml

Modified: myfaces/forrest/trunk/content/xdocs/tomahawk/extensionsFilter.xml
URL: http://svn.apache.org/viewcvs/myfaces/forrest/trunk/content/xdocs/tomahawk/extensionsFilter.xml?rev=358356&r1=358355&r2=358356&view=diff
==============================================================================
--- myfaces/forrest/trunk/content/xdocs/tomahawk/extensionsFilter.xml (original)
+++ myfaces/forrest/trunk/content/xdocs/tomahawk/extensionsFilter.xml Wed Dec 21 11:34:08 2005
@@ -14,11 +14,11 @@
 	<p>
 		Some MyFaces components do more than include some HTML in the pages.
 	    They may need additional support scripts, style sheets, images, ...<br/>
-	    Those resources are included in the MyFaces' jar file and the Extensions Filter add
+	    Those resources are included in the MyFaces' jar file and the Extensions Filter adds
 	    the code and URL needed to provide those resources to the generated HTML.
 	</p>
 	<p>
-		Some other components, like the file upload component (t:inputFileUpload) need to parse
+		Some other components, like the file upload component (t:inputFileUpload), need to parse
 		Multipart requests.<br/>
 		The extensions filter handles this as well.
 	</p>
@@ -29,29 +29,29 @@
 	This design has several benefits :</p>
 	<ol>
 		<li>It provides a clean separation between MyFaces' components and your webapp.</li>
-		<li>You don't have to include additional MyFaces' components related code or resources in your pages or webapp.</li>
-		<li>It provides great flexibility to the MyFaces' team upgrade the components, while keeping transparent backward compatibility.</li>
+		<li>You don't have to include additional MyFaces' components-related code or resources in your pages or webapp.</li>
+		<li>It provides flexibility so that the MyFaces' team can upgrade the components while keeping transparent backward compatibility.</li>
 		<li>It makes it possible for complex components to use many support resources without any burden on the page developer.</li>
-		<li>It loads only the resources really useful for the rendered components.</li>
+		<li>It loads only the resources useful for the rendered components.</li>
 		<li>It handles the MyFaces' resources caching.</li>
 	</ol>
 </section>
 <section>
 	<title>How does it work?</title>
-<p>	When a component needs a resource, is calls one of the org.apache.myfaces.component.html.util.AddResource methods
+<p>	When a component needs a resource, it calls one of the org.apache.myfaces.component.html.util.AddResource methods
 	(for example AddResource.addJavaScriptToHeader(InputHtmlRenderer.class, "sarissa.js", context); ).<br/>
-	This method add an attribute to the request so that the filter knows that is must include the given javascript, stylesheet
-	or resource link to the page.<br/>
-	The code for this resource is automatically included in the generated HTML.<br/>
-	The URL for an embedded resource	is constructed and always begins by /myfaces/ so that it can be intercepted by the filter
-	when the client need to load the resource.<br/>
-	When the clients fetches the resource, the filter decodes the URL, and serves the proper resource that is
-	embedded in MyFaces' jar.</p>
+	The AddResource methods add an attribute to the request so that the filter is notified to include the given javascript, stylesheet,
+	or resource link in the generated HTML for your JSF page.<br/>
+	The URL for an embedded resource begins with /faces/myFacesExtensionResource so that it can be intercepted by the filter
+	when the client needs to load the resource.<br/>
+	When the clients fetches the resource, the filter also decodes the URL, and serves the proper resource from the MyFaces' jar.</p>
 </section>
 <section>
 	<title>How do I configure it?</title><p>
 	In your web.xml, map this filter to the path used for the JSF pages (most likely *.jsf)
-	AND to the /faces/* path as in the following example :</p>
+	so the filter can update resource links on your JSF pages, and also map the filter to the /faces/* path
+	so it can serve page-independent resources like images, javascript files, and stylesheets.
+	Here's one example of configuring the extensions filter:</p>
 	<source>
 <![CDATA[
 <filter>
@@ -69,17 +69,27 @@
     </init-param>
 </filter>
 
-
+<!-- extension mapping for adding <script/>, <link/>, and other resource tags to JSF-pages  -->
 <filter-mapping>
-	<filter-name>MyFacesExtensionsFilter</filter-name>
-	<url-pattern>*.jsf</url-pattern>
+    <filter-name>MyFacesExtensionsFilter</filter-name>
+    <!-- servlet-name must match the name of your javax.faces.webapp.FacesServlet entry -->
+    <servlet-name>Faces Servlet</servlet-name>
 </filter-mapping>
+
+<!-- extension mapping for serving page-independent resources (javascript, stylesheets, images, etc.)  -->
 <filter-mapping>
-	<filter-name>MyFacesExtensionsFilter</filter-name>
-	<url-pattern>/faces/*</url-pattern>
-</filter-mapping>
+    <filter-name>MyFacesExtensionsFilter</filter-name>
+    <url-pattern>/faces/*</ url-pattern>
 		]]></source>
-</section>
+	<p>Alternate mapping using a url-pattern instead of a servlet-name (you still need the /faces/* mapping as well):</p>
+	<source>
+<![CDATA[
+<!-- extension mapping for adding <script/>, <link/>, and other resource tags to JSF-pages  -->
+<filter-mapping>
+    <filter-name>MyFacesExtensionsFilter</filter-name>
+    <url-pattern>*.jsf</url-pattern>
+</filter-mapping>
+		]]></source></section>
 <section>
 	<title>Under what circumstances am I *required* to use the extensions filter?</title><p>
 	If you just use standard JSF component, but don't use any MyFaces' extended component (beginning with t:),