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 java.net.*; 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-button-element"><button></a> 025 * element. 026 * 027 * <p> 028 * The button element represents a clickable button that can be used to submit forms, trigger actions, 029 * or perform other interactive functions. Unlike input elements, buttons can contain rich content 030 * including text, images, and other HTML elements. 031 * 032 * <h5 class='section'>Examples:</h5> 033 * <p class='bcode w800'> 034 * <jc>// Simple submit button</jc> 035 * Button <jv>btn1</jv> = <jsm>button</jsm>().type(<js>"submit"</js>).text(<js>"Submit Form"</js>); 036 * 037 * <jc>// Button with custom styling and click handler</jc> 038 * Button <jv>btn2</jv> = <jsm>button</jsm>() 039 * .type(<js>"button"</js>) 040 * .class_(<js>"btn btn-primary"</js>) 041 * .onclick(<js>"handleClick()"</js>) 042 * .text(<js>"Click Me"</js>); 043 * 044 * <jc>// Button with form override attributes</jc> 045 * Button <jv>btn3</jv> = <jsm>button</jsm>() 046 * .type(<js>"submit"</js>) 047 * .formaction(<js>"https://api.example.com/submit"</js>) 048 * .formmethod(<js>"post"</js>) 049 * .formtarget(<js>"_blank"</js>) 050 * .text(<js>"Submit to API"</js>); 051 * 052 * <jc>// Button with icon and text</jc> 053 * Button <jv>btn4</jv> = <jsm>button</jsm>() 054 * .type(<js>"button"</js>) 055 * .children( 056 * <jsm>span</jsm>().class_(<js>"icon"</js>).text(<js>"📧"</js>), 057 * <jsm>span</jsm>().text(<js>"Send Email"</js>) 058 * ); 059 * </p> 060 * 061 * <p> 062 * The following convenience methods are provided for constructing instances of this bean: 063 * <ul class='javatree'> 064 * <li class='jc'>{@link HtmlBuilder} 065 * <ul class='javatree'> 066 * <li class='jm'>{@link HtmlBuilder#button() button()} 067 * <li class='jm'>{@link HtmlBuilder#button(String, Object...) button(String, Object...)} 068 * </ul> 069 * </ul> 070 * </p> 071 * 072 * <h5 class='section'>See Also:</h5><ul> 073 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 074 * </ul> 075 */ 076@Marshalled(typeName = "button") 077public class Button extends HtmlElementMixed<Button> { 078 079 /** 080 * Creates an empty {@link Button} element. 081 */ 082 public Button() {} 083 084 /** 085 * Creates a {@link Button} element with the specified {@link Button#type(String)} attribute. 086 * 087 * @param type The {@link Button#type(String)} attribute. Can be <jk>null</jk> to unset the attribute. 088 */ 089 public Button(String type) { 090 type(type); 091 } 092 093 /** 094 * Creates a {@link Button} element with the specified {@link Button#type(String)} attribute and 095 * {@link Button#children(Object[])} nodes. 096 * 097 * @param type The {@link Button#type(String)} attribute. Can be <jk>null</jk> to unset the attribute. 098 * @param children The {@link Button#children(Object[])} nodes. Must not be <jk>null</jk>. 099 */ 100 public Button(String type, Object...children) { 101 type(type).children(children); 102 } 103 104 /** 105 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-autofocus">autofocus</a> attribute. 106 * 107 * <p> 108 * Automatically focus the form control when the page is loaded. 109 * 110 * @param value 111 * The new value for this attribute. 112 * Typically a {@link Boolean} or {@link String}. 113 * Can be <jk>null</jk> to unset the attribute. 114 * @return This object. 115 */ 116 public Button autofocus(Object value) { 117 attr("autofocus", value); 118 return this; 119 } 120 121 /** 122 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-disabled">disabled</a> attribute. 123 * 124 * <p> 125 * Whether the form control is disabled. 126 * 127 * <p> 128 * This attribute uses deminimized values: 129 * <ul> 130 * <li><jk>false</jk> - Attribute is not added</li> 131 * <li><jk>true</jk> - Attribute is added as <js>"disabled"</js></li> 132 * <li>Other values - Passed through as-is</li> 133 * </ul> 134 * 135 * @param value 136 * The new value for this attribute. 137 * Typically a {@link Boolean} or {@link String}. 138 * Can be <jk>null</jk> to unset the attribute. 139 * @return This object. 140 */ 141 public Button disabled(Object value) { 142 attr("disabled", deminimize(value, "disabled")); 143 return this; 144 } 145 146 /** 147 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute. 148 * 149 * <p> 150 * Associates the button with a form element by specifying the form's ID. This allows the button 151 * to be placed outside the form element while still being part of the form submission. 152 * 153 * <p> 154 * The value should match the ID of a form element in the same document. 155 * 156 * @param value The ID of the form element to associate with this button. Can be <jk>null</jk> to unset the attribute. 157 * @return This object. 158 */ 159 public Button form(String value) { 160 attr("form", value); 161 return this; 162 } 163 164 /** 165 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formaction">formaction</a> attribute. 166 * 167 * <p> 168 * Specifies the URL where the form data will be submitted when this button is clicked. 169 * Overrides the form's action attribute. 170 * 171 * <p> 172 * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 173 * Strings must be valid URIs. 174 * 175 * <p> 176 * URIs defined by {@link UriResolver} can be used for values. 177 * 178 * @param value The URL where the form data will be submitted. Can be <jk>null</jk>, in which case the attribute is stored with a <jk>null</jk> value (not removed). 179 * @return This object. 180 */ 181 public Button formaction(String value) { 182 attrUri("formaction", value); 183 return this; 184 } 185 186 /** 187 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formenctype">formenctype</a> attribute. 188 * 189 * <p> 190 * Specifies how form data should be encoded when submitted. Overrides the form's enctype attribute. 191 * 192 * <p> 193 * Possible values: 194 * <ul> 195 * <li><js>"application/x-www-form-urlencoded"</js> - Default encoding (default)</li> 196 * <li><js>"multipart/form-data"</js> - For file uploads</li> 197 * <li><js>"text/plain"</js> - Plain text encoding</li> 198 * </ul> 199 * 200 * @param value The encoding type for form submission. Can be <jk>null</jk> to unset the attribute. 201 * @return This object. 202 */ 203 public Button formenctype(String value) { 204 attr("formenctype", value); 205 return this; 206 } 207 208 /** 209 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formmethod">formmethod</a> attribute. 210 * 211 * <p> 212 * Specifies the HTTP method to use for form submission. Overrides the form's method attribute. 213 * 214 * <p> 215 * Possible values: 216 * <ul> 217 * <li><js>"get"</js> - Form data is sent as URL parameters</li> 218 * <li><js>"post"</js> - Form data is sent in the request body (default)</li> 219 * <li><js>"dialog"</js> - Used for forms within dialog elements</li> 220 * </ul> 221 * 222 * @param value The HTTP method for form submission. Can be <jk>null</jk> to unset the attribute. 223 * @return This object. 224 */ 225 public Button formmethod(String value) { 226 attr("formmethod", value); 227 return this; 228 } 229 230 /** 231 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formnovalidate">formnovalidate</a> 232 * attribute. 233 * 234 * <p> 235 * Specifies that form validation should be bypassed when this button submits the form. 236 * Overrides the form's novalidate attribute. 237 * 238 * <p> 239 * This attribute uses deminimized values: 240 * <ul> 241 * <li><jk>false</jk> - Form validation is performed (default)</li> 242 * <li><jk>true</jk> - Form validation is bypassed</li> 243 * <li>Other values - Passed through as-is</li> 244 * </ul> 245 * 246 * @param value Whether to bypass form validation. Can be <jk>null</jk> to unset the attribute. 247 * @return This object. 248 */ 249 public Button formnovalidate(String value) { 250 attr("formnovalidate", value); 251 return this; 252 } 253 254 /** 255 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formtarget">formtarget</a> attribute. 256 * 257 * <p> 258 * Specifies where to display the form response after submission. Overrides the form's target attribute. 259 * 260 * <p> 261 * Common values: 262 * <ul> 263 * <li><js>"_blank"</js> - Open in a new window/tab</li> 264 * <li><js>"_self"</js> - Open in the same frame (default)</li> 265 * <li><js>"_parent"</js> - Open in the parent frame</li> 266 * <li><js>"_top"</js> - Open in the full body of the window</li> 267 * <li><js>"framename"</js> - Open in a named frame</li> 268 * </ul> 269 * 270 * @param value Where to display the form response. Can be <jk>null</jk> to unset the attribute. 271 * @return This object. 272 */ 273 public Button formtarget(String value) { 274 attr("formtarget", value); 275 return this; 276 } 277 278 /** 279 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-menu">menu</a> attribute. 280 * 281 * <p> 282 * Specifies the ID of a menu element that should be displayed as a pop-up menu 283 * when the button is activated. 284 * 285 * <p> 286 * The value should match the ID of a menu element in the same document. 287 * 288 * @param value The ID of the menu element to display as a pop-up. Can be <jk>null</jk> to unset the attribute. 289 * @return This object. 290 */ 291 public Button menu(String value) { 292 attr("menu", value); 293 return this; 294 } 295 296 /** 297 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-name">name</a> attribute. 298 * 299 * <p> 300 * Specifies the name of the button. This name is used when the form is submitted and 301 * can be used to access the element via the form.elements API. 302 * 303 * <p> 304 * The name should be unique within the form and should not contain spaces or special characters. 305 * 306 * @param value The name of the button for submission and API access. Can be <jk>null</jk> to unset the attribute. 307 * @return This object. 308 */ 309 public Button name(String value) { 310 attr("name", value); 311 return this; 312 } 313 314 /** 315 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-button-type">type</a> attribute. 316 * 317 * <p> 318 * Specifies the type of button and its behavior when clicked. 319 * 320 * <p> 321 * Possible values: 322 * <ul> 323 * <li><js>"submit"</js> - Submits the form (default)</li> 324 * <li><js>"reset"</js> - Resets the form to its initial state</li> 325 * <li><js>"button"</js> - Generic button with no default behavior</li> 326 * </ul> 327 * 328 * @param value The type of button and its behavior. Can be <jk>null</jk> to unset the attribute. 329 * @return This object. 330 */ 331 public Button type(String value) { 332 attr("type", value); 333 return this; 334 } 335 336 /** 337 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-button-value">value</a> attribute. 338 * 339 * <p> 340 * Value to be used for form submission. 341 * 342 * @param value 343 * The new value for this attribute. 344 * Typically a {@link Number} or {@link String}. 345 * Can be <jk>null</jk> to unset the attribute. 346 * @return This object. 347 */ 348 public Button value(Object value) { 349 attr("value", value); 350 return this; 351 } 352}