001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.bean.html5; 018 019import static org.apache.juneau.commons.utils.Shorts.*; 020 021import org.apache.juneau.marshall.*; 022 023/** 024 * DTO for an HTML <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#the-select-element"><select></a> 025 * element. 026 * 027 * <p> 028 * The select element represents a control that provides a menu of options. It creates a dropdown 029 * list that allows users to select one or more options from a list. The select element contains 030 * option elements that define the available choices, and can be organized into groups using 031 * optgroup elements. 032 * 033 * <h2 class='section'>Examples:</h2> 034 * <p class='bcode w800'> 035 * <jk>import static</jk> org.apache.juneau.bean.html5.HtmlBuilder.*; 036 * 037 * <jc>// Simple select dropdown</jc> 038 * Select <jv>select1</jv> = <jsm>select</jsm>(<js>"color"</js>, 039 * <jsm>option</jsm>(<js>"red"</js>, <js>"Red"</js>), 040 * <jsm>option</jsm>(<js>"green"</js>, <js>"Green"</js>), 041 * <jsm>option</jsm>(<js>"blue"</js>, <js>"Blue"</js>) 042 * ); 043 * 044 * <jc>// Multiple selection</jc> 045 * Select <jv>select2</jv> = <jsm>select</jsm>(<js>"hobbies"</js>, 046 * <jsm>option</jsm>(<js>"reading"</js>, <js>"Reading"</js>), 047 * <jsm>option</jsm>(<js>"gaming"</js>, <js>"Gaming"</js>), 048 * <jsm>option</jsm>(<js>"sports"</js>, <js>"Sports"</js>) 049 * ).multiple(<jk>true</jk>).size(4); 050 * 051 * <jc>// Select with option groups</jc> 052 * Select <jv>select3</jv> = <jsm>select</jsm>(<js>"food"</js>, 053 * <jsm>optgroup</jsm>(<js>"Fruits"</js>, 054 * <jsm>option</jsm>(<js>"apple"</js>, <js>"Apple"</js>), 055 * <jsm>option</jsm>(<js>"banana"</js>, <js>"Banana"</js>) 056 * ), 057 * <jsm>optgroup</jsm>(<js>"Vegetables"</js>, 058 * <jsm>option</jsm>(<js>"carrot"</js>, <js>"Carrot"</js>), 059 * <jsm>option</jsm>(<js>"broccoli"</js>, <js>"Broccoli"</js>) 060 * ) 061 * ); 062 * 063 * <jc>// Disabled select</jc> 064 * Select <jv>select4</jv> = <jsm>select</jsm>(<js>"disabled"</js>) 065 * .disabled(<jk>true</jk>) 066 * .children( 067 * option().value("option1").text("Option 1") 068 * ); 069 * </p> 070 * 071 * <p> 072 * The following convenience methods are provided for constructing instances of this bean: 073 * <ul class='javatree'> 074 * <li class='jc'>{@link HtmlBuilder} 075 * <ul class='javatree'> 076 * <li class='jm'>{@link HtmlBuilder#select() select()} 077 * <li class='jm'>{@link HtmlBuilder#select(String, Object...) select(String, Object...)} 078 * </ul> 079 * </ul> 080 * 081 * <h2 class='section'>See Also:</h2><ul> 082 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 083 * </ul> 084 */ 085@Marshalled(typeName = "select") 086public class Select extends HtmlElementContainer<Select> { 087 088 /** 089 * Creates an empty {@link Select} element. 090 */ 091 public Select() {} 092 093 /** 094 * Creates a {@link Select} element with the specified {@link Select#name(String)} attribute and child nodes. 095 * 096 * @param name The {@link Select#name(String)} attribute. Can be <jk>null</jk> to unset the attribute. 097 * @param children The child nodes. Must not be <jk>null</jk>. 098 */ 099 public Select(String name, Object...children) { 100 name(name).children(children); 101 } 102 103 /** 104 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-autofocus">autofocus</a> attribute. 105 * 106 * <p> 107 * Automatically focus the form control when the page is loaded. 108 * 109 * @param value 110 * The new value for this attribute. 111 * Typically a {@link Boolean} or {@link String}. 112 * Can be <jk>null</jk> to unset the attribute. 113 * @return This object. 114 */ 115 public Select autofocus(Object value) { 116 attr("autofocus", value); 117 return this; 118 } 119 120 /** 121 * Convenience method for selecting a child {@link Option} after the options have already been populated. 122 * 123 * @param optionValue The option value. Can be <jk>null</jk> (no-op; no option is selected). 124 * @return This object. 125 */ 126 public Select choose(Object optionValue) { 127 if (nn(optionValue)) { 128 getChildren().forEach(x -> { 129 if (x instanceof Option o && eq(optionValue.toString(), o.getAttr(String.class, "value"))) 130 o.selected(true); 131 }); 132 } 133 return this; 134 } 135 136 /** 137 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-disabled">disabled</a> attribute. 138 * 139 * <p> 140 * Whether the form control is disabled. 141 * 142 * <p> 143 * This attribute uses deminimized values: 144 * <ul> 145 * <li><jk>false</jk> - Attribute is not added</li> 146 * <li><jk>true</jk> - Attribute is added as <js>"disabled"</js></li> 147 * <li>Other values - Passed through as-is</li> 148 * </ul> 149 * 150 * @param value 151 * The new value for this attribute. 152 * Typically a {@link Boolean} or {@link String}. 153 * Can be <jk>null</jk> to unset the attribute. 154 * @return This object. 155 */ 156 public Select disabled(Object value) { 157 attr("disabled", deminimize(value, "disabled")); 158 return this; 159 } 160 161 /** 162 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute. 163 * 164 * <p> 165 * Associates the select element with a form element by specifying the form's ID. This allows the select 166 * to be placed outside the form element while still being part of the form. 167 * 168 * <p> 169 * The value should match the ID of a form element in the same document. 170 * 171 * @param value The ID of the form element to associate with this select. Can be <jk>null</jk> to unset the attribute. 172 * @return This object. 173 */ 174 public Select form(String value) { 175 attr("form", value); 176 return this; 177 } 178 179 /** 180 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-select-multiple">multiple</a> attribute. 181 * 182 * <p> 183 * Whether to allow multiple values. 184 * 185 * <p> 186 * This attribute uses deminimized values: 187 * <ul> 188 * <li><jk>false</jk> - Attribute is not added</li> 189 * <li><jk>true</jk> - Attribute is added as <js>"multiple"</js></li> 190 * <li>Other values - Passed through as-is</li> 191 * </ul> 192 * 193 * @param value 194 * The new value for this attribute. 195 * Typically a {@link Boolean} or {@link String}. 196 * Can be <jk>null</jk> to unset the attribute. 197 * @return This object. 198 */ 199 public Select multiple(Object value) { 200 attr("multiple", deminimize(value, "multiple")); 201 return this; 202 } 203 204 /** 205 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-name">name</a> attribute. 206 * 207 * <p> 208 * Specifies the name of the select element. This name is used when the form is submitted and 209 * can be used to access the element via the form.elements API. 210 * 211 * <p> 212 * The name should be unique within the form and should not contain spaces or special characters. 213 * 214 * @param value The name of the select element for submission and API access. Can be <jk>null</jk> to unset the attribute. 215 * @return This object. 216 */ 217 public Select name(String value) { 218 attr("name", value); 219 return this; 220 } 221 222 /** 223 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-select-required">required</a> attribute. 224 * 225 * <p> 226 * Whether the control is required for form submission. 227 * 228 * @param value 229 * The new value for this attribute. 230 * Typically a {@link Boolean} or {@link String}. 231 * Can be <jk>null</jk> to unset the attribute. 232 * @return This object. 233 */ 234 public Select required(Object value) { 235 attr("required", value); 236 return this; 237 } 238 239 /** 240 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-select-size">size</a> attribute. 241 * 242 * <p> 243 * Specifies the number of visible options in a select element. If greater than 1, 244 * the select becomes a scrollable list instead of a dropdown. 245 * 246 * @param value The number of visible options (1 for dropdown, >1 for list). Can be <jk>null</jk> to unset the attribute. 247 * @return This object. 248 */ 249 public Select size(Object value) { 250 attr("size", value); 251 return this; 252 } 253 254}