You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by mk...@apache.org on 2006/03/02 02:56:13 UTC
svn commit: r382240 -
/myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml
Author: mkienenb
Date: Wed Mar 1 17:56:11 2006
New Revision: 382240
URL: http://svn.apache.org/viewcvs?rev=382240&view=rev
Log:
Restored latest version of extensions filter docs, and merged in new xdoc format.
Modified:
myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml
Modified: myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml
URL: http://svn.apache.org/viewcvs/myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml?rev=382240&r1=382239&r2=382240&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml (original)
+++ myfaces/tomahawk/trunk/core/src/site/xdoc/extensionsFilter.xml Wed Mar 1 17:56:11 2006
@@ -11,11 +11,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>
@@ -26,31 +26,30 @@
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 name="How does it work?">
-<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 name="How do I configure it?">
<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/myFacesExtensionResource/* 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 xml:space="preserve">
-
<filter>
<filter-name>MyFacesExtensionsFilter</filter-name>
<filter-class>org.apache.myfaces.component.html.util.ExtensionsFilter</filter-class>
@@ -66,16 +65,27 @@
</init-param>
</filter>
+<!-- extension mapping for adding <script/>, <link/>, and other resource tags to JSF-pages -->
+<filter-mapping>
+ <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>*.jsf</url-pattern>
+ <filter-name>MyFacesExtensionsFilter</filter-name>
+ <url-pattern>/faces/myFacesExtensionResource/*</url-pattern>
</filter-mapping>
+ </source>
+ <p>Alternate mapping using a url-pattern instead of a servlet-name (you still need the /faces/myFacesExtensionResource/* mapping as well):</p>
+ <source xml:space="preserve">
+<!-- extension mapping for adding <script/>, <link/>, and other resource tags to JSF-pages -->
<filter-mapping>
- <filter-name>MyFacesExtensionsFilter</filter-name>
- <url-pattern>/faces/*</url-pattern>
+ <filter-name>MyFacesExtensionsFilter</filter-name>
+ <url-pattern>*.jsf</url-pattern>
</filter-mapping>
- </source>
+ </source>
</section>
<section name="Under what circumstances am I *required* to use the extensions filter?">
<p>