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 componentFamily = UIInput.COMPONENT_FAMILY, 51 rendererType = RendererTypes.SUGGEST, 52 allowedChildComponenents = { 53 "org.apache.myfaces.tobago.SelectItems", 54 "org.apache.myfaces.tobago.SelectItem" 55 }/* todo , 56 behaviors = { 57 @Behavior( 58 name = ClientBehaviors.SUGGEST, 59 isDefault = true) 60 }*/) 61 public interface SuggestTagDeclaration extends HasIdBindingAndRendered { 62 63 /** 64 * {@link javax.el.MethodExpression} which generates a list of suggested input values based on 65 * the currently entered text, which could be retrieved via getSubmittedValue() on the UIIn. 66 * The expression has to evaluate to a public method which has a javax.faces.component.UIInput parameter 67 * and returns a List<String>, a List<org.apache.myfaces.tobago.model.AutoSuggestItem> 68 * or a org.apache.myfaces.tobago.model.AutoSuggestItems. 69 * 70 * @deprecated since 3.0.0. 71 * Please use an <code><tc:selectItems></code> tag or a list of <code><tc:selectItem></code> tags. 72 */ 73 @Deprecated 74 @TagAttribute 75 @UIComponentTagAttribute(type = {}, 76 expression = DynamicExpression.METHOD_EXPRESSION_REQUIRED, 77 methodSignature = "javax.faces.component.UIInput", 78 methodReturnType = "java.lang.Object") 79 void setSuggestMethod(String suggestMethod); 80 81 /** 82 * Minimum number of characters to type before the list will be requested. 83 * If the value is 0, there will be send an initial list to the client. 84 * So, if you set <pre>update="false"</pre> this value should be 0. 85 */ 86 @TagAttribute 87 @UIComponentTagAttribute(type = "java.lang.Integer", defaultValue = "1") 88 void setMinimumCharacters(String minimumCharacters); 89 90 /** 91 * Time in milli seconds before the list will be requested (by AJAX). 92 */ 93 @TagAttribute 94 @UIComponentTagAttribute(type = "java.lang.Integer", defaultValue = "200") 95 void setDelay(String delay); 96 97 /** 98 * The maximum number of item to display in the drop down list. 99 */ 100 @TagAttribute 101 @UIComponentTagAttribute(type = "java.lang.Integer", defaultValue = "10") 102 void setMaximumItems(String maximumItems); 103 104 /** 105 * The real size of the result list. 106 * Typically the result list will be cropped (in the backend) to save memory. 107 * This value can be set, to show the user there are more results for the given string. 108 * If the value is -1, no hint will be displayed. 109 */ 110 @TagAttribute 111 @UIComponentTagAttribute(type = "java.lang.Integer", defaultValue = "-1") 112 void setTotalCount(String totalCount); 113 114 /** 115 * TODO: not implemented yet 116 * <p> 117 * Additional client side filtering of the result list. 118 * This is useful when sending the full list initially to the client and 119 * setting <code>update=false</code>. 120 * </p> 121 * <p> 122 * Possible values are: 123 * </p> 124 * <dl> 125 * <dt>all</dt> 126 * <dd>no filtering</dd> 127 * <dt>prefix</dt> 128 * <dd>checks if the suggested string starts with the typed text</dd> 129 * <dt>contains</dt> 130 * <dd>checks if the typed text is inside of the suggested string</dd> 131 * </dl> 132 * <p> 133 * The filter will only applied on the client side and 134 * only if server updated (by AJAX) are turned off (<code>update=false</code>); 135 * </p> 136 */ 137 @TagAttribute 138 @UIComponentTagAttribute( 139 type = "org.apache.myfaces.tobago.model.SuggestFilter", 140 defaultValue = "SuggestFilter.ALL", 141 allowedValues = { 142 SuggestFilter.STRING_ALL, 143 SuggestFilter.STRING_PREFIX, 144 SuggestFilter.STRING_CONTAINS}) 145 void setFilter(String filter); 146 147 /** 148 * TODO: not implemented yet 149 * <p> 150 * Should the list be updated while typing (via AJAX). This is the default behavior. 151 * If you set this value to <code>false</code>, please set the <code>minimumCharacters="0"</code>. 152 * </p> 153 */ 154 @TagAttribute 155 @UIComponentTagAttribute(type = "boolean", defaultValue = "true") 156 void setUpdate(String update); 157 158 /** 159 * <p> 160 * If a suggest menu is available, it will be rendered on the component, not in the '.tobago-page-menuStore'. 161 * </p> 162 */ 163 @TagAttribute 164 @UIComponentTagAttribute(type = "boolean", defaultValue = "false") 165 void setLocalMenu(String localMenu); 166 167 /** 168 * The query is the string typed by the user. 169 */ 170 @TagAttribute 171 @UIComponentTagAttribute(generate = false, isTransient = true) 172 void setQuery(String query); 173 }