View Javadoc

1   /*
2    * $Id: Autocompleter.java 502294 2007-02-01 17:28:00Z niallp $
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  package org.apache.struts2.components;
22  
23  import javax.servlet.http.HttpServletRequest;
24  import javax.servlet.http.HttpServletResponse;
25  
26  import org.apache.struts2.views.annotations.StrutsTag;
27  import org.apache.struts2.views.annotations.StrutsTagAttribute;
28  
29  import com.opensymphony.xwork2.util.ValueStack;
30  
31  /***
32   * <p>The autocomplete tag is a combobox that can autocomplete text entered on the input box.
33   * When used on the "simple" theme, the autocompleter can be used like the ComboBox.
34   * When used on the "ajax" theme, the list can be retieved from an action. This action must
35   * return a JSON list in the format:</p>
36   * <pre>
37   * [
38   *   ["Text 1","Value1"],
39   *   ["Text 2","Value2"],
40   *   ["Text 3","Value3"]
41   * ]
42   * </pre>
43   * <!-- START SNIPPET: ajaxJavadoc -->
44   * <B>THE FOLLOWING IS ONLY VALID WHEN AJAX IS CONFIGURED</B>
45   * <ul>
46   *      <li>href</li>
47   *      <li>errorText</li>
48   *      <li>listenTopics</li>
49   *      <li>notifyTopics</li>
50   *      <li>listenTopics</li>
51   *      <li>formId</li>
52   *      <li>formFilter</li>
53   *      <li>indicator</li>
54   *      <li>loadOnTextChange</li>
55   *      <li>loadMinimumCount</li>
56   *      <li>showDownArrow</li>
57   *      <li>searchType</li>
58   * </ul>
59   * 'dropdownWidth' width in pixels of the drodpdown, same as autocompleter's width by default<p/>
60   * 'dropdownHeight' height in pixels of the drodown, 120 px by default<p/>
61   * 'forceValidOption' if invalid option is selected, clear autocompleter's text when focus is lost<p/>
62   * 'autoComplete', if true, make suggestions on the textbox<p/>
63   * 'formId' is the id of the html form whose fields will be seralized and passed as parameters
64   * in the request.<p/>
65   * 'formFilter' is the name of a function which will be used to filter the fields that will be
66   * seralized. This function takes as a parameter the element and returns true if the element
67   * should be included.<p/>
68   * 'listenTopics' comma separated list of topics names, that will trigger a request
69   * 'indicator' element to be shown while the request executing
70   * 'showErrorTransportText': whether errors should be displayed (on 'targets')<p/>
71   * 'loadOnTextChange' options will be reloaded everytime a character is typed on the textbox<p/>
72   * 'loadMinimumCount' minimum number of characters that will force the content to be loaded<p/>
73   * 'showDownError' show or hide the down arrow button
74   * 'searchType' how the search must be performed, options are: "startstring", "startword" and "substring"<p/>
75   * 'notifyTopics' comma separated list of topics names, that will be published. Three parameters are passed:<p/>
76   * <ul>
77   *      <li>data: selected value when type='valuechanged'</li>
78   *      <li>type: 'before' before the request is made, 'valuechanged' when selection changes, 'load' when the request succeeds, or 'error' when it fails</li>
79   *      <li>request: request javascript object, when type='load' or type='error'</li>
80   * <ul>
81   *
82   */
83  @StrutsTag(name="autocompleter", tldTagClass="org.apache.struts2.views.jsp.ui.AutocompleterTag", description="Renders a combobox with autocomplete and AJAX capabilities")
84  public class Autocompleter extends ComboBox {
85      public static final String TEMPLATE = "autocompleter";
86      final private static String COMPONENT_NAME = Autocompleter.class.getName();
87  
88      protected String forceValidOption;
89      protected String searchType;
90      protected String autoComplete;
91      protected String delay;
92      protected String disabled;
93      protected String href;
94      protected String dropdownWidth;
95      protected String dropdownHeight;
96      protected String formId;
97      protected String formFilter;
98      protected String listenTopics;
99      protected String notifyTopics;
100     protected String indicator;
101     protected String loadOnTextChange;
102     protected String loadMinimumCount;
103     protected String showDownArrow;
104 
105     public Autocompleter(ValueStack stack, HttpServletRequest request,
106             HttpServletResponse response) {
107         super(stack, request, response);
108     }
109 
110     protected String getDefaultTemplate() {
111         return TEMPLATE;
112     }
113 
114     public String getComponentName() {
115         return COMPONENT_NAME;
116     }
117 
118 
119     public void evaluateExtraParams() {
120         super.evaluateExtraParams();
121 
122         if (forceValidOption != null)
123             addParameter("forceValidOption", findValue(forceValidOption,
124                     Boolean.class));
125         if (searchType != null) {
126             String type =  findString(searchType);
127             if(type != null)
128                 addParameter("searchType", type.toUpperCase());
129         }
130         if (autoComplete != null)
131             addParameter("autoComplete", findValue(autoComplete, Boolean.class));
132         if (delay != null)
133             addParameter("delay", findValue(delay, Integer.class));
134         if (disabled != null)
135             addParameter("disabled", findValue(disabled, Boolean.class));
136         if (href != null) {
137             addParameter("href", findString(href));
138             addParameter("mode", "remote");
139         }
140         if (dropdownHeight != null)
141             addParameter("dropdownHeight", findValue(dropdownHeight, Integer.class));
142         if (dropdownWidth != null)
143             addParameter("dropdownWidth", findValue(dropdownWidth, Integer.class));
144         if (formFilter != null)
145           addParameter("formFilter", findString(formFilter));
146         if (formId != null)
147           addParameter("formId", findString(formId));
148         if (listenTopics != null)
149           addParameter("listenTopics", findString(listenTopics));
150         if (notifyTopics != null)
151           addParameter("notifyTopics", findString(notifyTopics));
152         if (indicator != null)
153             addParameter("indicator", findString(indicator));
154         if (loadOnTextChange != null)
155             addParameter("loadOnTextChange", findValue(loadOnTextChange, Boolean.class));
156         if (loadMinimumCount != null)
157             addParameter("loadMinimumCount", findValue(loadMinimumCount, Integer.class));
158         if (showDownArrow != null)
159             addParameter("showDownArrow", findValue(showDownArrow, Boolean.class));
160         else
161             addParameter("showDownArrow", Boolean.TRUE);
162         //get the key value
163         if(name != null) {
164             String keyNameExpr = "%{" + name + "Key}";
165             addParameter("key", findString(keyNameExpr));
166         }
167     }
168 
169     protected Object findListValue() {
170         return (list != null) ? findValue(list, Object.class) : null;
171     }
172 
173     @StrutsTagAttribute(description="Whether autocompleter should make suggestion on the textbox", type="Boolean", defaultValue="false")
174     public void setAutoComplete(String autoComplete) {
175         this.autoComplete = autoComplete;
176     }
177 
178     @StrutsTagAttribute(description="Enable or disable autocompleter", type="Boolean", defaultValue="false")
179     public void setDisabled(String disabled) {
180         this.disabled = disabled;
181     }
182 
183     @StrutsTagAttribute(description="Force selection to be one of the options", type="Boolean", defaultValue="false")
184     public void setForceValidOption(String forceValidOption) {
185         this.forceValidOption = forceValidOption;
186     }
187 
188     @StrutsTagAttribute(description="The URL used to load the options")
189     public void setHref(String href) {
190         this.href = href;
191     }
192 
193     @StrutsTagAttribute(description="Delay before making the search", type="Integer", defaultValue="100")
194     public void setDelay(String searchDelay) {
195         this.delay = searchDelay;
196     }
197 
198     @StrutsTagAttribute(description="how the search must be performed, options are: 'startstring', 'startword' " +
199                 "and 'substring'", defaultValue="stringstart")
200     public void setSearchType(String searchType) {
201         this.searchType = searchType;
202     }
203 
204     @StrutsTagAttribute(description="Dropdown's height in pixels", type="Integer", defaultValue="120")
205     public void setDropdownHeight(String height) {
206         this.dropdownHeight = height;
207     }
208 
209     @StrutsTagAttribute(description="Dropdown's width", type="Integer", defaultValue="same as textbox")
210     public void setDropdownWidth(String width) {
211         this.dropdownWidth = width;
212     }
213 
214     @StrutsTagAttribute(description="Function name used to filter the fields of the form")
215     public void setFormFilter(String formFilter) {
216       this.formFilter = formFilter;
217     }
218 
219     @StrutsTagAttribute(description="Form id whose fields will be serialized and passed as parameters")
220     public void setFormId(String formId) {
221       this.formId = formId;
222     }
223 
224     @StrutsTagAttribute(description="Topic that will trigger a reload")
225     public void setListenTopics(String listenTopics) {
226       this.listenTopics = listenTopics;
227     }
228 
229     @StrutsTagAttribute(description="Topics that will be published when content is reloaded")
230     public void setNotifyTopics(String onValueChangedPublishTopic) {
231       this.notifyTopics = onValueChangedPublishTopic;
232     }
233 
234     @StrutsTagAttribute(description="Id of element that will be shown while request is made")
235     public void setIndicator(String indicator) {
236         this.indicator = indicator;
237     }
238 
239     @StrutsTagAttribute(description="Minimum number of characters that will force the content to be loaded", type="Integer", defaultValue="3")
240     public void setLoadMinimumCount(String loadMinimumCount) {
241         this.loadMinimumCount = loadMinimumCount;
242     }
243 
244     @StrutsTagAttribute(description="Options will be reloaded everytime a character is typed on the textbox", type="Boolean", defaultValue="true")
245     public void setLoadOnTextChange(String loadOnType) {
246         this.loadOnTextChange = loadOnType;
247     }
248 
249     @StrutsTagAttribute(description="Show or hide the down arrow button", type="Boolean", defaultValue="true")
250     public void setShowDownArrow(String showDownArrow) {
251         this.showDownArrow = showDownArrow;
252     }
253 
254     // Override as not required
255     @StrutsTagAttribute(description="Iteratable source to populate from.")
256     public void setList(String list) {
257         super.setList(list);
258     }
259 }