View Javadoc

1   /*
2    * $Id: ComboBox.java 651946 2008-04-27 13:41:38Z apetrelli $
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  package org.apache.struts2.components;
23  
24  import java.util.Collection;
25  import java.util.Iterator;
26  import java.util.Map;
27  
28  import javax.servlet.http.HttpServletRequest;
29  import javax.servlet.http.HttpServletResponse;
30  
31  import org.apache.struts2.views.annotations.StrutsTag;
32  import org.apache.struts2.views.annotations.StrutsTagAttribute;
33  import org.apache.struts2.util.MakeIterator;
34  
35  import com.opensymphony.xwork2.util.ValueStack;
36  
37  /***
38   * <!-- START SNIPPET: javadoc -->
39   * The combo box is basically an HTML INPUT of type text and HTML SELECT grouped together to give you a combo box
40   * functionality. You can place text in the INPUT control by using the SELECT control or type it in directly in
41   * the text field.<p/>
42   *
43   * In this example, the SELECT will be populated from id=year attribute. Counter is itself an Iterator. It will
44   * span from first to last. The population is done via javascript, and requires that this tag be surrounded by a
45   * &lt;form&gt;.<p/>
46   *
47   * Note that unlike the &lt;s:select/&gt; tag, there is no ability to define the individual &lt;option&gt; tags' id attribute
48   * or content separately. Each of these is simply populated from the toString() method of the list item. Presumably
49   * this is because the select box isn't intended to actually submit useful data, but to assist the user in filling
50   * out the text field.<p/>
51   * <!-- END SNIPPET: javadoc -->
52   *
53   * <p/> <b>Examples</b>
54   *
55   * <pre>
56   * <!-- START SNIPPET: example -->
57   * JSP:
58   * &lt;-- Example One --&gt;
59   * &lt;s:bean name="struts.util.Counter" var="year"&gt;
60   *   &lt;s:param name="first" value="text('firstBirthYear')"/&gt;
61   *   &lt;s:param name="last" value="2000"/&gt;
62   *
63   *   &lt;s:combobox label="Birth year" size="6" maxlength="4" name="birthYear" list="#year"/&gt;
64   * &lt;/s:bean&gt;
65   *
66   * &lt;-- Example Two --&gt;
67   * <s:combobox
68   *     label="My Favourite Fruit"
69   *     name="myFavouriteFruit"
70   *     list="{'apple','banana','grape','pear'}"
71   *     headerKey="-1"
72   *     headerValue="--- Please Select ---"
73   *     emptyOption="true"
74   *     value="banana" />
75   *
76   * &lt;-- Example Two --&gt;
77   * <s:combobox
78   *    label="My Favourite Color"
79   *    name="myFavouriteColor"
80   *    list="#{'red':'red','green':'green','blue':'blue'}"
81   *    headerKey="-1"
82   *    headerValue="--- Please Select ---"
83   *    emptyOption="true"
84   *    value="green" />
85   *
86   * Velocity:
87   * #tag( ComboBox "label=Birth year" "size=6" "maxlength=4" "name=birthYear" "list=#year" )
88   * <!-- END SNIPPET: example -->
89   * </pre>
90   *
91   */
92  @StrutsTag(name="combobox", tldTagClass="org.apache.struts2.views.jsp.ui.ComboBoxTag", description="Widget that fills a text box from a select")
93  public class ComboBox extends TextField {
94      final public static String TEMPLATE = "combobox";
95  
96      protected String list;
97      protected String listKey;
98      protected String listValue;
99      protected String headerKey;
100     protected String headerValue;
101     protected String emptyOption;
102 
103 
104     public ComboBox(ValueStack stack, HttpServletRequest request, HttpServletResponse response) {
105         super(stack, request, response);
106     }
107 
108     protected String getDefaultTemplate() {
109         return TEMPLATE;
110     }
111 
112     public void evaluateExtraParams() {
113         super.evaluateExtraParams();
114 
115         Object value = findListValue();
116 
117         if (headerKey != null) {
118             addParameter("headerKey", findString(headerKey));
119         }
120         if (headerValue != null) {
121             addParameter("headerValue", findString(headerValue));
122         }
123         if (emptyOption != null) {
124             addParameter("emptyOption", findValue(emptyOption, Boolean.class));
125         }
126 
127         if (value != null) {
128             if (value instanceof Collection) {
129                 Collection tmp = (Collection) value;
130                 addParameter("list", tmp);
131                 if (listKey != null) {
132                     addParameter("listKey", listKey);
133                 }
134                 if (listValue != null) {
135                     addParameter("listValue", listValue);
136                 }
137             } else if (value instanceof Map) {
138                 Map tmp = (Map) value;
139                 addParameter("list", MakeIterator.convert(tmp));
140                 addParameter("listKey", "key");
141                 addParameter("listValue", "value");                
142             } else { // also covers "if (value.getClass().isArray())"
143                 Iterator i = MakeIterator.convert(value);
144                 addParameter("list", i);
145                 if (listKey != null) {
146                     addParameter("listKey", listKey);
147                 }
148                 if (listValue != null) {
149                     addParameter("listValue", listValue);
150                 }
151             }
152         }
153     }
154 
155     protected Object findListValue() {
156         return findValue(list, "list",
157                 "You must specify a collection/array/map/enumeration/iterator. " +
158                 "Example: people or people.{name}");
159     }
160 
161     @StrutsTagAttribute(description="Iteratable source to populate from. " +
162                 "If this is missing, the select widget is simply not displayed.", required=true)
163     public void setList(String list) {
164         this.list = list;
165     }
166 
167     @StrutsTagAttribute(description="Decide if an empty option is to be inserted. Default false.")
168     public void setEmptyOption(String emptyOption) {
169         this.emptyOption = emptyOption;
170     }
171 
172     @StrutsTagAttribute(description="Set the header key for the header option.")
173     public void setHeaderKey(String headerKey) {
174         this.headerKey = headerKey;
175     }
176 
177     @StrutsTagAttribute(description="Set the header value for the header option.")
178     public void setHeaderValue(String headerValue) {
179         this.headerValue = headerValue;
180     }
181 
182     @StrutsTagAttribute(description="Set the key used to retrive the option key.")
183     public void setListKey(String listKey) {
184         this.listKey = listKey;
185     }
186 
187     @StrutsTagAttribute(description="Set the value used to retrive the option value.")
188     public void setListValue(String listValue) {
189         this.listValue = listValue;
190     }
191 
192 
193 }