myfaces-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From svieu...@apache.org
Subject cvs commit: incubator-myfaces/src/documentation/content/xdocs site.xml
Date Wed, 06 Apr 2005 22:52:02 GMT
svieujot    2005/04/06 15:52:02

  Modified:    src/documentation/content/xdocs site.xml
  Added:       src/documentation/content/xdocs/docs extensionsFilter.xml
  Log:
  Added documentation for the Extensions Filter.
  
  Revision  Changes    Path
  1.1                  incubator-myfaces/src/documentation/content/xdocs/docs/extensionsFilter.xml
  
  Index: extensionsFilter.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.2//EN" "document-v12.dtd">
  
  <document>
  
  <header>
      <title>Apache MyFaces - MyFaces' Extensions Filter</title>
  </header>
  
  <body>
  
  <section>
  <title>What is the Extensions Filter for?</title>
  	<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
  	    the code and URL needed to provide those resources to the generated HTML.
  	</p>
  	<p>
  		Some other components, like the file upload component (x:inputFileUpload) need to parse
  		Multipart requests.<br/>
  		The extensions filter handles this as well.
  	</p>
  </section>
  <section>
  	<title>Why is this useful?</title>
  	This design has several benefits :
  	<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>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 handles the MyFaces' resources caching.</li>
  	</ol>
  </section>
  <section>
  	<title>How does it work?</title>
  	When a component needs a resource, is 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.
  </section>
  <section>
  	<title>How do I configure it?</title>
  	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 :
  	<source>
  <![CDATA[
  <filter>
  	<filter-name>MyFacesExtensionsFilter</filter-name>
  	<filter-class>org.apache.myfaces.component.html.util.ExtensionsFilter</filter-class>
      <init-param>
          <param-name>maxFileSize</param-name>
          <param-value>20m</param-value>
          <description>Set the size limit for uploaded files.
              Format: 10 - 10 bytes
                      10k - 10 KB
                      10m - 10 MB
                      1g - 1 GB
          </description>
      </init-param>
  </filter>
  
  
  <filter-mapping>
  	<filter-name>MyFacesExtensionsFilter</filter-name>
  	<url-pattern>*.jsf</url-pattern>
  </filter-mapping>
  <filter-mapping>
  	<filter-name>MyFacesExtensionsFilter</filter-name>
  	<url-pattern>/faces/*</url-pattern>
  </filter-mapping>
  		]]></source>
  </section>
  <section>
  	<title>Under what circumstances am I *required* to use the extensions filter?</title>
  	If you just use standard JSF component, but don't use any MyFaces' extended component (beginning
with x:),
  	then you don't need the Extensions Filter.<br/>
  	However, if you use some of the MyFaces' extended components like x:inputFileUpload, x:inputHTtml,
x:inputCalendar, ...
  	then you most likely need to have this filter configured in your webapp.
  </section>
  <section>
  	<title>Does this impact performance?</title>
  	The filter hasn't any significant impact the response time.<br/>
  	However, as the filter has to cache the whole response in memory before writing it out
to the client, it slightly increases the memory usage.
  </section>
  </body>
      
  <footer>
      	<legal>Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems,
Inc. in the United States and other countries.<br />
  	&copy; 2004, Apache Software Foundation
  	</legal>
  </footer>
  
  </document>
  
  
  1.15      +1 -0      incubator-myfaces/src/documentation/content/xdocs/site.xml
  
  Index: site.xml
  ===================================================================
  RCS file: /home/cvs/incubator-myfaces/src/documentation/content/xdocs/site.xml,v
  retrieving revision 1.14
  retrieving revision 1.15
  diff -u -r1.14 -r1.15
  --- site.xml	1 Apr 2005 05:12:56 -0000	1.14
  +++ site.xml	6 Apr 2005 22:52:02 -0000	1.15
  @@ -26,6 +26,7 @@
   		<ri label="MyFaces and RI" href="risamples.html"/>
   		<tomcat55 label="MyFaces and Tomcat5.5" href="tomcat55.html"/>
   		<portlet label="MyFaces' Portlet Support" href="portlet.html"/>
  +		<extensionsFilter label="MyFaces' Extensions Filter" href="extensionsFilter.html"/>
   		<compatibility label="Compatibility" href="compatibility.html"/>
   		<faq label="FAQ" href="faq.html" />
   		<jars label="JARs" href="jars.html" />
  
  
  

Mime
View raw message