You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@myfaces.apache.org by mb...@apache.org on 2005/11/08 22:23:19 UTC
svn commit: r331893 - in /myfaces:
impl/trunk/tld/entities/extended_data_table_attributes.xml
tomahawk/trunk/src/java/org/apache/myfaces/component/html/util/AddResource.java
tomahawk/trunk/tld/tomahawk.tld
Author: mbr
Date: Tue Nov 8 13:23:10 2005
New Revision: 331893
URL: http://svn.apache.org/viewcvs?rev=331893&view=rev
Log:
applied patch for MYFACES-792, MYFACES-793, MYFACES-794, thanks Simon Kitching.
Modified:
myfaces/impl/trunk/tld/entities/extended_data_table_attributes.xml
myfaces/tomahawk/trunk/src/java/org/apache/myfaces/component/html/util/AddResource.java
myfaces/tomahawk/trunk/tld/tomahawk.tld
Modified: myfaces/impl/trunk/tld/entities/extended_data_table_attributes.xml
URL: http://svn.apache.org/viewcvs/myfaces/impl/trunk/tld/entities/extended_data_table_attributes.xml?rev=331893&r1=331892&r2=331893&view=diff
==============================================================================
--- myfaces/impl/trunk/tld/entities/extended_data_table_attributes.xml (original)
+++ myfaces/impl/trunk/tld/entities/extended_data_table_attributes.xml Tue Nov 8 13:23:10 2005
@@ -4,7 +4,16 @@
<rtexprvalue>false</rtexprvalue>
<description>
Indicates whether the state of the whole DataModel should be saved and
- restored.
+ restored. When set to false, the value-binding for the "value" attribute
+ of this table is executed each time the page is rendered. When set to
+ true, that value-binding is only executed when the component is first
+ created, and the DataModel state is thereafter saved/restored automatically
+ by the component.
+
+ When column sorting is used for a table this property needs to be false
+ so that the DataModel can be updated to reflect any changes in the
+ sort criteria.
+
Default: false
</description>
</attribute>
@@ -13,7 +22,7 @@
<required>false</required>
<rtexprvalue>false</rtexprvalue>
<description>
- A formula that overrides the defaut row index in the construction of table's
+ A formula that overrides the default row index in the construction of table's
body components.
Example : #{myRowVar.key}
Warning, the EL should evaluate to a unique value for each row !
@@ -25,6 +34,10 @@
<rtexprvalue>false</rtexprvalue>
<description>
Value reference to a model property that gives the current sort column name.
+ The target String property is set to the "columnName" of whichever column has been
+ chosen to sort by, and the method which is bound to the "value" attribute
+ of this table (ie which provides the DataModel used) is expected to use this
+ property to determine how to sort the DataModel's contents.
</description>
</attribute>
<attribute>
@@ -33,6 +46,11 @@
<rtexprvalue>false</rtexprvalue>
<description>
Value reference to a model property that gives the current sort direction.
+ The target Boolean property is set to true when the selected sortColumn
+ should be sorted in ascending order, and false otherwise. The method which
+ is bound to the "value" attribute of this table (ie which provides the DataModel
+ used) is expected to use this property to determine how to sort the DataModel's
+ contents.
</description>
</attribute>
<attribute>
Modified: myfaces/tomahawk/trunk/src/java/org/apache/myfaces/component/html/util/AddResource.java
URL: http://svn.apache.org/viewcvs/myfaces/tomahawk/trunk/src/java/org/apache/myfaces/component/html/util/AddResource.java?rev=331893&r1=331892&r2=331893&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/src/java/org/apache/myfaces/component/html/util/AddResource.java (original)
+++ myfaces/tomahawk/trunk/src/java/org/apache/myfaces/component/html/util/AddResource.java Tue Nov 8 13:23:10 2005
@@ -34,9 +34,20 @@
/**
* This is a utility class to render link to resources used by custom components.
- * Mostly used to avoid having to include <script src="..."></script>
+ * Mostly used to avoid having to include [script src="..."][/script]
* in the head of the pages before using a component.
- *
+ * <p>
+ * When used together with the ExtensionsFilter, this class can allow components
+ * in the body of a page to emit script and stylesheet references into the page
+ * head section. The relevant methods on this object simply queue the changes,
+ * and when the page is complete the ExtensionsFilter calls back into this
+ * class to allow it to insert the commands into the buffered response.
+ * <p>
+ * This class also works with the ExtensionsFilter to allow components to
+ * emit references to javascript/css/etc which are bundled in the component's
+ * jar file. Special URLs are generated which the ExtensionsFilter will later
+ * handle by retrieving the specified resource from the classpath.
+ *
* @author Sylvain Vieujot (latest modification by $Author$)
* @version $Revision$ $Date$
*/
@@ -70,10 +81,31 @@
_contextPath = contextPath;
}
+ /**
+ * Map of AddResource instances keyed by context path. This map will have
+ * more than one entry only if the myfaces library is in the "shared"
+ * classpath of a container where more than one webapp can see it
+ * simultaneously.
+ */
private static final Map _addResourceMap = new HashMap();
- private static AddResource getInstance(String contextPath)
+ /*
+ * Internal factory method.
+ * <p>
+ * Return an instance of AddResource keyed by context path, or create one
+ * if no such instance already exists. Note that the same AddResource object
+ * is shared among all threads servicing the same webapp, so all methods
+ * on this class are required to be threadsafe.
+ * <p>
+ * Note that this method is package-scope for the purposes of unit-testing only.
+ * This method should be treated as private by non-test code.
+ */
+ static AddResource getInstance(String contextPath)
{
+ // Yes, this method does use a variant of the "double locking" idiom
+ // which is well documented to be invalid for general use. However
+ // it is believed safe for use here because AddResource objects in
+ // _addResourceMap are never removed or replaced.
AddResource instance = (AddResource) _addResourceMap.get(contextPath);
if (instance == null)
{
@@ -100,14 +132,29 @@
return getInstance(request.getContextPath());
}
- // Methodes to Add resources
+ // Methods to add resources
+ /**
+ * Insert a [script src="url"] entry at the current location in the response.
+ * The resource is expected to be in the classpath, at the same location as the
+ * specified component + "/resource".
+ * <p>
+ * Example: when customComponent is class example.Widget, and
+ * resourceName is script.js, the resource will be retrieved from
+ * "example/Widget/resource/script.js" in the classpath.
+ */
public void addJavaScriptHere(FacesContext context, Class myfacesCustomComponent,
String resourceName) throws IOException
{
addJavaScriptHere(context, new MyFacesResourceHandler(myfacesCustomComponent, resourceName));
}
+ /**
+ * Insert a [script src="url"] entry at the current location in the response.
+ *
+ * @param uri is the location of the desired resource, relative to the base
+ * directory of the webapp (ie its contextPath).
+ */
public void addJavaScriptHere(FacesContext context, String uri) throws IOException
{
ResponseWriter writer = context.getResponseWriter();
@@ -119,6 +166,17 @@
writer.endElement(HTML.SCRIPT_ELEM);
}
+ /**
+ * Insert a [script src="url"] entry at the current location in the response.
+ *
+ * @param context
+ *
+ * @param resourceHandler is an object which specifies exactly how to build the url
+ * that is emitted into the script tag. Code which needs to generate URLs in ways
+ * that this class does not support by default can implement a custom ResourceHandler.
+ *
+ * @throws IOException
+ */
public void addJavaScriptHere(FacesContext context, ResourceHandler resourceHandler)
throws IOException
{
@@ -169,11 +227,20 @@
}
/**
- * Adds the given Javascript resource at the specified document position by supplying
- * an resourcehandler instance. Use this method to have full control about building
- * the reference url to identify the resource and to customize how the resource
- * is written to the response.
+ * Adds the given Javascript resource to the document header at the specified
+ * document positioy by supplying a resourcehandler instance.
+ * <p>
+ * Use this method to have full control about building the reference url
+ * to identify the resource and to customize how the resource is
+ * written to the response. In most cases, however, one of the convenience
+ * methods on this class can be used without requiring a custom ResourceHandler
+ * to be provided.
+ * <p>
* If the script has already been referenced, it's added only once.
+ * <p>
+ * Note that this method <i>queues</i> the javascript for insertion, and that
+ * the script is inserted into the buffered response by the ExtensionsFilter
+ * after the page is complete.
*/
public void addJavaScriptAtPosition(FacesContext context, int position, ResourceHandler resourceHandler)
{
@@ -181,8 +248,16 @@
}
/**
- * Adds the given Javascript resource at the specified document position.
- * If the script has already been referenced, it's added only once.
+ * Insert a [script src="url"] entry into the document header at the
+ * specified document position. If the script has already been
+ * referenced, it's added only once.
+ * <p>
+ * The resource is expected to be in the classpath, at the same location as the
+ * specified component + "/resource".
+ * <p>
+ * Example: when customComponent is class example.Widget, and
+ * resourceName is script.js, the resource will be retrieved from
+ * "example/Widget/resource/script.js" in the classpath.
*/
public void addJavaScriptAtPosition(FacesContext context, int position, Class myfacesCustomComponent,
String resourceName)
@@ -192,8 +267,14 @@
}
/**
- * Adds the given Javascript resource at the specified document position.
- * If the script has already been referenced, it's added only once.
+ * Insert a [script src="url"] entry into the document header at the
+ * specified document position. If the script has already been
+ * referenced, it's added only once.
+ *
+ * @param defer specifies whether the html attribute "defer" is set on the
+ * generated script tag. If this is true then the browser will continue
+ * processing the html page without waiting for the specified script to
+ * load and be run.
*/
public void addJavaScriptAtPosition(FacesContext context, int position, Class myfacesCustomComponent,
String resourceName, boolean defer)
@@ -203,8 +284,12 @@
}
/**
- * Adds the given Javascript resource at the specified document position.
- * If the script has already been referenced, it's added only once.
+ * Insert a [script src="url"] entry into the document header at the
+ * specified document position. If the script has already been
+ * referenced, it's added only once.
+ *
+ * @param uri is the location of the desired resource, relative to the base
+ * directory of the webapp (ie its contextPath).
*/
public void addJavaScriptAtPosition(FacesContext context, int position, String uri)
{
Modified: myfaces/tomahawk/trunk/tld/tomahawk.tld
URL: http://svn.apache.org/viewcvs/myfaces/tomahawk/trunk/tld/tomahawk.tld?rev=331893&r1=331892&r2=331893&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/tld/tomahawk.tld (original)
+++ myfaces/tomahawk/trunk/tld/tomahawk.tld Tue Nov 8 13:23:10 2005
@@ -801,13 +801,22 @@
<tag-class>org.apache.myfaces.custom.sortheader.HtmlCommandSortHeaderTag</tag-class>
<body-content>JSP</body-content>
<description>
+ <p>
Clickable sort column header.
Must be nested inside an extended data_table tag.
This tag is derived from the standard command_link tag and
has the additional attributes columnName and arrow.
- Note: In contrary to normal command links the default for the "immediate"
- attribute is "true".
- </description>
+ </p>
+ <p>
+ Note: In contrast to normal command links, the default for the "immediate"
+ attribute is "true". This is desirable as it avoids validating all input
+ fields in the enclosing form when the column sort order changes. HOWEVER
+ when the <i>table</i> contains input components "immediate" <i>must</i> be
+ set to false; otherwise input fields will render blank after a sort, or
+ will show their old values (ie will not appear to sort though output
+ fields in the table will sort) when sort ordering is changed.
+ </p>
+ </description>
&ui_command_attributes;
&html_universal_attributes;
&html_event_handler_attributes;