View Javadoc

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