View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  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,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  
20  package org.apache.myfaces.tobago.internal.taglib.component;
21  
22  import org.apache.myfaces.tobago.apt.annotation.DynamicExpression;
23  import org.apache.myfaces.tobago.apt.annotation.Tag;
24  import org.apache.myfaces.tobago.apt.annotation.TagAttribute;
25  import org.apache.myfaces.tobago.apt.annotation.UIComponentTag;
26  import org.apache.myfaces.tobago.apt.annotation.UIComponentTagAttribute;
27  import org.apache.myfaces.tobago.component.RendererTypes;
28  import org.apache.myfaces.tobago.internal.taglib.declaration.HasIdBindingAndRendered;
29  import org.apache.myfaces.tobago.model.SuggestFilter;
30  
31  import javax.faces.component.UIInput;
32  
33  /**
34   * Renders a list of suggested texts for a given input field.
35   *
36   * Basic features:
37   * <ul>
38   *   <li>provide a list directly while rendering (not AJAX needed) [todo]</li>
39   *   <li>update by typing (AJAX)</li>
40   *   <li>minimum number of typed characters (to avoid useless requests)</li>
41   *   <li>update delay (useful for optimization)</li>
42   *   <li>filter on client side (useful for optimization) [todo]</li>
43   * </ul>
44   *
45   * @since 2.0.0
46   */
47  @Tag(name = "suggest")
48  @UIComponentTag(
49      uiComponent = "org.apache.myfaces.tobago.component.UISuggest",
50      uiComponentBaseClass = "org.apache.myfaces.tobago.internal.component.AbstractUISuggest",
51      uiComponentFacesClass = "javax.faces.component.UIComponentBase",
52      componentFamily = UIInput.COMPONENT_FAMILY,
53      rendererType = RendererTypes.SUGGEST,
54      allowedChildComponenents = {
55          "org.apache.myfaces.tobago.SelectItems",
56          "org.apache.myfaces.tobago.SelectItem"
57      }/* todo ,
58      behaviors = {
59          @Behavior(
60              name = ClientBehaviors.SUGGEST,
61              isDefault = true)
62      }*/)
63  public interface SuggestTagDeclaration extends HasIdBindingAndRendered {
64  
65    /**
66     * MethodBinding which generates a list of suggested input values based on
67     * the currently entered text, which could be retrieved via getSubmittedValue() on the UIIn.
68     * The expression has to evaluate to a public method which has a javax.faces.component.UIInput parameter
69     * and returns a List&lt;String&gt;, a List&lt;org.apache.myfaces.tobago.model.AutoSuggestItem&gt;
70     * or a org.apache.myfaces.tobago.model.AutoSuggestItems.
71     *
72     * @deprecated Please use an <code>&lt;tc:selectItems&gt;</code> tag or a list of <code>&lt;tc:selectItem&gt;</code>
73     * tags (TODO: not implemented yet).
74     */
75    @Deprecated
76    @TagAttribute
77    @UIComponentTagAttribute(type = {},
78        expression = DynamicExpression.METHOD_EXPRESSION_REQUIRED,
79        methodSignature = "javax.faces.component.UIInput",
80        methodReturnType = "java.lang.Object")
81    void setSuggestMethod(String suggestMethod);
82  
83    /**
84     * Minimum number of characters to type before the list will be requested.
85     * If the value is 0, there will be send an initial list to the client.
86     * So, if you set <pre>update="false"</pre> this value should be 0.
87     */
88    @TagAttribute
89    @UIComponentTagAttribute(type = "java.lang.Integer", defaultValue = "1")
90    void setMinimumCharacters(String minimumCharacters);
91  
92    /**
93     * Time in milli seconds before the list will be requested (by AJAX).
94     */
95    @TagAttribute
96    @UIComponentTagAttribute(type = "java.lang.Integer", defaultValue = "200")
97    void setDelay(String delay);
98  
99    /**
100    * The maximum number of item to display in the drop down list.
101    */
102   @TagAttribute
103   @UIComponentTagAttribute(type = "java.lang.Integer", defaultValue = "10")
104   void setMaximumItems(String maximumItems);
105 
106   /**
107    * The real size of the result list.
108    * Typically the result list will be cropped (in the backend) to save memory.
109    * This value can be set, to show the user there are more results for the given string.
110    * If the value is -1, no hint will be displayed.
111    */
112   @TagAttribute
113   @UIComponentTagAttribute(type = "java.lang.Integer", defaultValue = "-1")
114   void setTotalCount(String totalCount);
115 
116   /**
117    * TODO: not implemented yet
118    * <p>
119    * Additional client side filtering of the result list.
120    * This is useful when sending the full list initially to the client and
121    * setting <code>update=false</code>.
122    * </p>
123    * <p>
124    * Possible values are:
125    * </p>
126    * <dl>
127    *   <dt>all</dt>
128    *   <dd>no filtering</dd>
129    *   <dt>prefix</dt>
130    *   <dd>checks if the suggested string starts with the typed text</dd>
131    *   <dt>contains</dt>
132    *   <dd>checks if the typed text is inside of the suggested string</dd>
133    * </dl>
134    * <p>
135    * The filter will only applied on the client side and
136    * only if server updated (by AJAX) are turned off (<code>update=false</code>);
137    * </p>
138    */
139   @TagAttribute
140   @UIComponentTagAttribute(
141       type = "org.apache.myfaces.tobago.model.SuggestFilter",
142       defaultValue = "SuggestFilter.ALL",
143       allowedValues = {
144           SuggestFilter.STRING_ALL,
145           SuggestFilter.STRING_PREFIX,
146           SuggestFilter.STRING_CONTAINS})
147   void setFilter(String filter);
148 
149   /**
150    * TODO: not implemented yet
151    * <p>
152    * Should the list be updated while typing (via AJAX). This is the default behaviour.
153    * If you set this value to <code>false</code>, please set the <code>minimumCharacters="0"</code>.
154    * </p>
155    */
156   @TagAttribute
157   @UIComponentTagAttribute(type = "boolean", defaultValue = "true")
158   void setUpdate(String update);
159 
160   /**
161    * The query is the string typed by the user.
162    */
163   @TagAttribute
164   @UIComponentTagAttribute(generate = false, isTransient = true)
165   void setQuery(String query);
166 }