Update Ajax Tags javadocs

git-svn-id: https://svn.apache.org/repos/asf/struts/struts2/trunk@528326 13f79535-47bb-0310-9956-ffa450edef68
2026-09-11 00:29:40 +00:00 · 2007-04-13 02:41:20 +00:00
parent d0f5fbe668
commit 8706f16380
2 changed files with 65 additions and 31 deletions
@@ -38,8 +38,8 @@ import com.opensymphony.xwork2.util.ValueStack;
 * <!-- END SNIPPET: javadoc -->
 * <p>Examples</p>
 * 
- * <p>Update target content with html returned from an action:</p>
 * <!-- START SNIPPET: example1 -->
+ * <p>Update target content with html returned from an action:</p>
 * <pre>
 * &lt;div id="div1"&gt;Div 1&lt;/div&gt;
 * &lt;s:url id="ajaxTest" value="/AjaxTest.action"/&gt;
@@ -50,8 +50,8 @@ import com.opensymphony.xwork2.util.ValueStack;
 * </pre>
 * <!-- END SNIPPET: example1 -->
 * 
- * <p>Submit form(anchor inside the form):</p>
 * <!-- START SNIPPET: example2 -->
+ * <p>Submit form(anchor inside the form):</p>
 * <pre>
 * &lt;s:form id="form" action="AjaxTest"&gt;
 *      &lt;input type="textbox" name="data"&gt;
@@ -60,8 +60,8 @@ import com.opensymphony.xwork2.util.ValueStack;
 * </pre>
 * <!-- END SNIPPET: example2 -->
 * 
- * <p>Submit form(anchor outside the form)</p>
 * <!-- START SNIPPET: example3 -->
+ * <p>Submit form(anchor outside the form)</p>
 * <pre>
 * &lt;s:form id="form" action="AjaxTest"&gt;
 *      &lt;input type="textbox" name="data"&gt;   
@@ -71,8 +71,8 @@ import com.opensymphony.xwork2.util.ValueStack;
 * </pre>
 * <!-- END SNIPPET: example3 -->
 * 
- * <p>Using topics:</p>
 * <!-- START SNIPPET: example4 -->
+ * <p>Using topics:</p>
 * <pre>
 * <script type="text/javascript">
 * dojo.event.topic.subscribe("/before", function(data, type, e){
@@ -87,7 +87,6 @@ import com.opensymphony.xwork2.util.ValueStack;
 * &lt;sx:a beforeNotifyTopics="/before"&gt;Publish topics&lt;/sx:a&gt;
 * </pre> 
 * <!-- END SNIPPET: example4 -->
- * </pre>
 */
@StrutsTag(name="a", tldTagClass="org.apache.struts2.dojo.views.jsp.ui.AnchorTag", description="Renders an HTML anchor element that when clicked calls a URL via remote XMLHttpRequest and updates " +
                "its targets content")
@@ -33,55 +33,90 @@ import com.opensymphony.xwork2.util.ValueStack;
 /**
 * <!-- START SNIPPET: javadoc -->
 * <p>The autocomplete tag is a combobox that can autocomplete text entered on the input box. If an action
- * is used to populate the autocompleter, the output of the action must be a well formed JSON string. The 
- * autocompleter expects and array of arrays of length 2, where the first element is the text displayed and
- * the second is the value.</p>
- * <!-- END SNIPPET: javadoc -->
+ * is used to populate the autocompleter, the output of the action must be a well formed JSON string. </p>
+ * <p>The autocompleter follows this rule to find its datasource:<p>
+ * <p>1. If the response is an array, assume that it contains 2-dimension array elements, like:
 * <pre>
- * <!-- START SNIPPET: examples -->
- * <b>Autocompleter that gets its list from an action:</b>
- *
- * &lt;sx:autocompleter name="autocompleter1" href="%{jsonList}"/&gt;
- *
- * Which expects a response like:
- * 
 * [
 *      ["Text1", "Value1"],
 *      ["Text2", "Value2"]
 * ]
+ * </pre>
+ * <p>2. If a value is specified in the "dataFieldName" attribute, and the response has a field with that
+ * name, assume that's the datasource, which can be an array of 2-dimension array elements, or a map, 
+ * like (assuming dataFieldName="states"):</p>
+ * <pre>
+ * {
+ *      "states" : [
+ *           ["Alabama","AL"],
+ *           ["Alaska","AK"]
+ *      ]
+ * }     
 * 
- * Or (note that now the response is a JSON object, instead of an array, and a field inside the object matches the autocompleter's name):
+ * or
 * 
 * {
- *      autocompleter1:[
- *           ["Text1", "Value1"],
- *           ["Text2", "Value2"]
+ *      "states" : {
+ *            "Alabama" : "AL",
+ *            "Alaska"  : "AK"
+ *      }
+ * }
+ * </pre>
+ * <p>4. If there is a field that starts with the value specified on the "name" attribute, assume 
+ * that's the datasource, like (assuming name="state"):</p>
+ * <pre>
+ * {
+ *      "states" : [
+ *           ["Alabama","AL"],
+ *           ["Alaska","AK"]
 *      ]
 * }
+ * </pre>
+ * <p>5. Use first array that is found, like:<p>
+ * <pre>
+ * {
+ *      "anything" : [
+ *            ["Text1", "Value1"],
+ *            ["Text2", "Value2"]
+ *     ]       
+ * }
+ * </pre>
+ * <!-- END SNIPPET: javadoc -->
+ * <p>Examples</p>
+ * <!-- START SNIPPET: example1 -->
+ * <p>Autocompleter that gets its list from an action:</p>
+ * <pre>
+ * &lt;sx:autocompleter name="autocompleter1" href="%{jsonList}"/&gt;
+ * </pre>
+ * <!-- END SNIPPET: example1 -->
 * 
- * The name of the field that contains the data for the autocompleter can be specified using the "dataFieldName" attribute.
- * 
- * <b>Autocompleter that uses a list:</b>
- *
+ * <!-- START SNIPPET: example2 -->
+ * <p>Autocompleter that uses a list:</p>
+ * <pre>
 * &lt;s:autocompleter name="test"  list="{'apple','banana','grape','pear'}" autoComplete="false"/&gt;
+ * </pre>
+ * <!-- END SNIPPET: example2 -->
 * 
- * <b>Autocompleter that reloads its content everytime the text changes (and the length of the text is greater than 3):</b>
- * 
+ * <!-- START SNIPPET: example3 -->
+ * <p>Autocompleter that reloads its content everytime the text changes (and the length of the text is greater than 3):</p>
+ * <pre>
 * &lt;sx:autocompleter name="mvc" href="%{jsonList}" loadOnTextChange="true" loadMinimumCount="3"/&gt;
 * 
 * The text entered on the autocompleter is passed as a parameter to the url specified in "href", like (text is "struts"):
 *  
 * http://host/example/myaction.do?mvc=struts
+ * </pre>
+ * <!-- END SNIPPET: example3 -->
 * 
- * <b>Linking two autocompleters:</b>
- * 
+ * <!-- START SNIPPET: example4 -->
+ * <p>Linking two autocompleters:</p>
+ * <pre>
 * &lt;form id="selectForm"&gt;
 *      &lt;sx:autocompleter  name="select" list="{'fruits','colors'}"  valueNotifyTopics="/changed" /&gt;
 * &lt;/form&gt;  
 * &lt;sx:autocompleter  href="%{jsonList}" formId="selectForm" listenTopics="/changed"/&gt;
- * 
- * <!-- END SNIPPET: examples -->
- * <pre>
+ * </pre>
+ * <!-- END SNIPPET: example4 -->
 */
@StrutsTag(name="autocompleter", tldTagClass="org.apache.struts2.dojo.views.jsp.ui.AutocompleterTag", description="Renders a combobox with autocomplete and AJAX capabilities")
 public class Autocompleter extends ComboBox {