svn commit: r345867 - in /myfaces/tomahawk/trunk: src/java/org/apache/myfaces/custom/updateactionlistener/UpdateActionListener.java tld/tomahawk.tld

[ba...@apache.org]

Author: baranda
Date: Mon Nov 21 00:36:24 2005
New Revision: 345867

URL: http://svn.apache.org/viewcvs?rev=345867&view=rev
Log:
Applied documentation patch for MYFACES-834. Thanks to Simon Kitching

Modified:
    myfaces/tomahawk/trunk/src/java/org/apache/myfaces/custom/updateactionlistener/UpdateActionListener.java
    myfaces/tomahawk/trunk/tld/tomahawk.tld

Modified: myfaces/tomahawk/trunk/src/java/org/apache/myfaces/custom/updateactionlistener/UpdateActionListener.java
URL: http://svn.apache.org/viewcvs/myfaces/tomahawk/trunk/src/java/org/apache/myfaces/custom/updateactionlistener/UpdateActionListener.java?rev=345867&r1=345866&r2=345867&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/src/java/org/apache/myfaces/custom/updateactionlistener/UpdateActionListener.java (original)
+++ myfaces/tomahawk/trunk/src/java/org/apache/myfaces/custom/updateactionlistener/UpdateActionListener.java Mon Nov 21 00:36:24 2005
@@ -27,6 +27,34 @@
 import javax.faces.event.ActionListener;
 
 /**
+ * Set an arbitrary property on a managed bean when an "action" component is
+ * selected by the user.
+ * <p>
+ * An instance of this listener type can be attached to any UIComponent which
+ * is an ActionSource (eg a link or button). When the associated component
+ * fires its action event, this listener will read the value specified by
+ * attribute "value" and assign it to the property specified by attribute
+ * "property". The value attribute may be a literal value or may be a
+ * value-binding; the property is always expected to be a value-binding.
+ * <p>
+ * An optional Converter may be associated with this listener, and if present
+ * will be invoked to convert the value to the datatype expected by the
+ * target property. When no converter is available, a default one will be
+ * retrieved from the Application object.
+ * <p>
+ * A common use for this listener is to attach it to an HtmlCommandLink
+ * component, storing some constant value into a managed bean property.
+ * After the navigation associated with that link is done, components in
+ * the new view can look at that property to determine which link was
+ * clicked.
+ * <p>
+ * Both the fetching of "value" and the updating of "property" occur in
+ * the invoke-application phase unless "immediate" is set on the ActionSource
+ * component in which case they both occur in the apply-request-values phase.
+ * The update is guaranteed to occur before the invocation of the method
+ * specified by attribute "action" on the ActionSource (because all
+ * actionListeners are executed before the action attribute).
+ * <p>
  * @author Manfred Geiler (latest modification by $Author$)
  * @version $Revision$ $Date$
  */

Modified: myfaces/tomahawk/trunk/tld/tomahawk.tld
URL: http://svn.apache.org/viewcvs/myfaces/tomahawk/trunk/tld/tomahawk.tld?rev=345867&r1=345866&r2=345867&view=diff
==============================================================================
--- myfaces/tomahawk/trunk/tld/tomahawk.tld (original)
+++ myfaces/tomahawk/trunk/tld/tomahawk.tld Mon Nov 21 00:36:24 2005
@@ -2354,23 +2354,37 @@
         <tag-class>org.apache.myfaces.custom.updateactionlistener.UpdateActionListenerTag</tag-class>
         <body-content>JSP</body-content>
         <description>
-            Registers a org.apache.myfaces.custom.updateactionlistener.UpdateActionListener at the
-            parent component.
+            Registers an org.apache.myfaces.custom.updateactionlistener.UpdateActionListener at the
+            parent component (which must be an ActionSource). When the parent's action fires the
+            specified value is evaluated, then written into the specified property.
         </description>
         <attribute>
             <name>property</name>
             <required>true</required>
             <rtexprvalue>false</rtexprvalue>
+            <description>
+                A value-binding that specifies a property to be updated when the parent's
+                action occurs.
+            </description>
         </attribute>
         <attribute>
             <name>value</name>
             <required>true</required>
             <rtexprvalue>false</rtexprvalue>
+            <description>
+                A literal value or value-binding that specifies what will be assigned to the
+                destination specified by the property attribute.
+            </description>
         </attribute>
         <attribute>
             <name>converter</name>
             <required>false</required>
             <rtexprvalue>false</rtexprvalue>
+            <description>
+                The name of a registered Converter object which will be invoked to convert the
+                value into an appropriate datatype for assigning to the specified property.
+                If not specified then an appropriate converter will be selected automatically.
+            </description>
         </attribute>
     </tag>