svn commit: r330012 - /myfaces/forrest/trunk/content/xdocs/tomahawk/javascriptListener.xml

[mb...@apache.org]

Author: mbr
Date: Tue Nov  1 01:51:54 2005
New Revision: 330012

URL: http://svn.apache.org/viewcvs?rev=330012&view=rev
Log:
patch from Sharath Reddy for MYFACES-766

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

Modified: myfaces/forrest/trunk/content/xdocs/tomahawk/javascriptListener.xml
URL: http://svn.apache.org/viewcvs/myfaces/forrest/trunk/content/xdocs/tomahawk/javascriptListener.xml?rev=330012&r1=330011&r2=330012&view=diff
==============================================================================
--- myfaces/forrest/trunk/content/xdocs/tomahawk/javascriptListener.xml (original)
+++ myfaces/forrest/trunk/content/xdocs/tomahawk/javascriptListener.xml Tue Nov  1 01:51:54 2005
@@ -12,7 +12,11 @@
         <section>
             <title>Description</title>
             <p>
-                Value change listener on client side.
+                This component replicates the 'Value Change Listener' functionality on the client side. It can be used
+                when the user would like a change in the value of one control to trigger off changes in the states of 
+                other controls. One or more Javascript Listeners can be nested within the source control (a control 
+                belonging to the 'javax.faces.Input' family). When the value of the source control is modified, the 
+                listeners are triggered and the states of the target controls modified.
             </p>
         </section>
         <!-- screen shot -->
@@ -53,20 +57,72 @@
         <section>
             <title>Usage</title>
             <source>
-&lt;t:jsValueChangeListener for="Bean"
-                            property="Bean"
-                            expressionValue="{true|false}" /&gt;
+                &lt;t:jsValueChangeListener for="id"
+                            property="property"
+                            expressionValue="{true|false}" 
+                            bodyTagEvent="eventName" /&gt;
             </source>
         </section>
         <!-- Syntax -->
         <section>
             <title>Syntax</title>
             <note label="&lt;t:jsValueChangeListener&gt;">
-                <code>for - the control to observe.</code><br/>
-                <code>property - the property to observe.</code><br/>
-                <code>expressionValue - the condition to evaluate.</code><br/>
+                <code>for - the id of the target control</code><br/>
+                <code>expressionValue - the javascript expression to evaluate. The keyword '$srcElem' resolves to 
+                    the source control and the keyword '$destElem' resolves to the target control </code><br/>
+                <code>property(optional) - The result of the evaluated expression is assigned to the specified property 
+                    of the target control</code><br/>
+                <code>bodyEventTag(optional) - Events are triggered by the 'onchange' event of the source control. Here, 
+                    an additional event can be specified (onload?)</code><br/>
             </note>
         </section>
+
+        <!-- Examples -->
+        <section>
+            <title>Examples</title>
+            <p>
+               Some examples will throw more light on the usage of this component.
+            </p>
+        
+            <p>
+            <strong>Example 1</strong><br/>
+                Suppose we have two text fields on a page. We would like to keep the value of the second text field 
+                in sync with the value of the first. This can be accomplised with the following code:
+            </p>
+            <source>
+                &lt;h:inputText id="text1"&gt;
+                    &lt;t:jsValueChangeListener for="text2" property="value" 
+                                                expressionValue="$srcElem.value" /&gt;
+                &lt;/h:inputText&gt;
+                &lt;h:inputText id="text2"/&gt;
+            </source>
+            <p> 
+                When the value of text1 changes, the 'onchange' event is triggered. The javascript expression specified by 
+                'expressionValue' is evaluated, and the result is assigned to the specified property (in this case, 'value') 
+                of the target control.
+            </p>notified
+
+            <p>
+            <strong>Example 2</strong><br/>
+                Sometimes, the evalution of the javascript expression itself causes the desired side-effect. In this case, 
+                it is not necessary to specify the 'property' attribute for the target control. In this example, we have 
+                a combo-box, and we want the selection of a specific value in the combo-box to cause a text box to be hidden.
+            </p>
+            <source>
+       &lt;h:selectOneMenu id="selone_menu_colors" value="red" styleClass="selectOneMenu"&gt;
+           &lt;f:selectItems value="#{carconf.colors}" /&gt;
+           &lt;t:jsValueChangeListener for="selone_menu_subcolors" 
+             expressionValue="($srcElem.options[$srcElem.selectedIndex].value=='black')?
+             $destElem.style.display='inline':$destElem.style.display='none';"/&gt;
+       &lt;/h:selectOneMenu&gt;
+       &lt;h:inputText id="selone_menu_subcolors"/&gt;
+            </source>
+            <p> 
+                The evaluation of the expression causes the text box to be hidden when the appropriate value is selected.
+            </p>
+        
+       </section>
+
         <!-- Instructions -->
         <section>
             <title>Instructions</title>