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 * <h2 class='section'>Examples:</h2> 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 * 071 * <h2 class='section'>See Also:</h2><ul> 072 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 073 * </ul> 074 */ 075@Marshalled(typeName = "button") 076public class Button extends HtmlElementMixed<Button> { 077 078 /** 079 * Creates an empty {@link Button} element. 080 */ 081 public Button() {} 082 083 /** 084 * Creates a {@link Button} element with the specified {@link Button#type(String)} attribute. 085 * 086 * @param type The {@link Button#type(String)} attribute. Can be <jk>null</jk> to unset the attribute. 087 */ 088 public Button(String type) { 089 type(type); 090 } 091 092 /** 093 * Creates a {@link Button} element with the specified {@link Button#type(String)} attribute and 094 * {@link Button#children(Object[])} nodes. 095 * 096 * @param type The {@link Button#type(String)} attribute. Can be <jk>null</jk> to unset the attribute. 097 * @param children The {@link Button#children(Object[])} nodes. Must not be <jk>null</jk>. 098 */ 099 public Button(String type, Object...children) { 100 type(type).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 Button autofocus(Object value) { 116 attr("autofocus", value); 117 return this; 118 } 119 120 /** 121 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-disabled">disabled</a> attribute. 122 * 123 * <p> 124 * Whether the form control is disabled. 125 * 126 * <p> 127 * This attribute uses deminimized values: 128 * <ul> 129 * <li><jk>false</jk> - Attribute is not added</li> 130 * <li><jk>true</jk> - Attribute is added as <js>"disabled"</js></li> 131 * <li>Other values - Passed through as-is</li> 132 * </ul> 133 * 134 * @param value 135 * The new value for this attribute. 136 * Typically a {@link Boolean} or {@link String}. 137 * Can be <jk>null</jk> to unset the attribute. 138 * @return This object. 139 */ 140 public Button disabled(Object value) { 141 attr("disabled", deminimize(value, "disabled")); 142 return this; 143 } 144 145 /** 146 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute. 147 * 148 * <p> 149 * Associates the button with a form element by specifying the form's ID. This allows the button 150 * to be placed outside the form element while still being part of the form submission. 151 * 152 * <p> 153 * The value should match the ID of a form element in the same document. 154 * 155 * @param value The ID of the form element to associate with this button. Can be <jk>null</jk> to unset the attribute. 156 * @return This object. 157 */ 158 public Button form(String value) { 159 attr("form", value); 160 return this; 161 } 162 163 /** 164 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formaction">formaction</a> attribute. 165 * 166 * <p> 167 * Specifies the URL where the form data will be submitted when this button is clicked. 168 * Overrides the form's action attribute. 169 * 170 * <p> 171 * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}. 172 * Strings must be valid URIs. 173 * 174 * <p> 175 * URIs defined by {@link UriResolver} can be used for values. 176 * 177 * @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). 178 * @return This object. 179 */ 180 public Button formaction(String value) { 181 attrUri("formaction", value); 182 return this; 183 } 184 185 /** 186 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formenctype">formenctype</a> attribute. 187 * 188 * <p> 189 * Specifies how form data should be encoded when submitted. Overrides the form's enctype attribute. 190 * 191 * <p> 192 * Possible values: 193 * <ul> 194 * <li><js>"application/x-www-form-urlencoded"</js> - Default encoding (default)</li> 195 * <li><js>"multipart/form-data"</js> - For file uploads</li> 196 * <li><js>"text/plain"</js> - Plain text encoding</li> 197 * </ul> 198 * 199 * @param value The encoding type for form submission. Can be <jk>null</jk> to unset the attribute. 200 * @return This object. 201 */ 202 public Button formenctype(String value) { 203 attr("formenctype", value); 204 return this; 205 } 206 207 /** 208 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formmethod">formmethod</a> attribute. 209 * 210 * <p> 211 * Specifies the HTTP method to use for form submission. Overrides the form's method attribute. 212 * 213 * <p> 214 * Possible values: 215 * <ul> 216 * <li><js>"get"</js> - Form data is sent as URL parameters</li> 217 * <li><js>"post"</js> - Form data is sent in the request body (default)</li> 218 * <li><js>"dialog"</js> - Used for forms within dialog elements</li> 219 * </ul> 220 * 221 * @param value The HTTP method for form submission. Can be <jk>null</jk> to unset the attribute. 222 * @return This object. 223 */ 224 public Button formmethod(String value) { 225 attr("formmethod", value); 226 return this; 227 } 228 229 /** 230 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formnovalidate">formnovalidate</a> 231 * attribute. 232 * 233 * <p> 234 * Specifies that form validation should be bypassed when this button submits the form. 235 * Overrides the form's novalidate attribute. 236 * 237 * <p> 238 * This attribute uses deminimized values: 239 * <ul> 240 * <li><jk>false</jk> - Form validation is performed (default)</li> 241 * <li><jk>true</jk> - Form validation is bypassed</li> 242 * <li>Other values - Passed through as-is</li> 243 * </ul> 244 * 245 * @param value Whether to bypass form validation. Can be <jk>null</jk> to unset the attribute. 246 * @return This object. 247 */ 248 public Button formnovalidate(String value) { 249 attr("formnovalidate", value); 250 return this; 251 } 252 253 /** 254 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formtarget">formtarget</a> attribute. 255 * 256 * <p> 257 * Specifies where to display the form response after submission. Overrides the form's target attribute. 258 * 259 * <p> 260 * Common values: 261 * <ul> 262 * <li><js>"_blank"</js> - Open in a new window/tab</li> 263 * <li><js>"_self"</js> - Open in the same frame (default)</li> 264 * <li><js>"_parent"</js> - Open in the parent frame</li> 265 * <li><js>"_top"</js> - Open in the full body of the window</li> 266 * <li><js>"framename"</js> - Open in a named frame</li> 267 * </ul> 268 * 269 * @param value Where to display the form response. Can be <jk>null</jk> to unset the attribute. 270 * @return This object. 271 */ 272 public Button formtarget(String value) { 273 attr("formtarget", value); 274 return this; 275 } 276 277 /** 278 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-menu">menu</a> attribute. 279 * 280 * <p> 281 * Specifies the ID of a menu element that should be displayed as a pop-up menu 282 * when the button is activated. 283 * 284 * <p> 285 * The value should match the ID of a menu element in the same document. 286 * 287 * @param value The ID of the menu element to display as a pop-up. Can be <jk>null</jk> to unset the attribute. 288 * @return This object. 289 */ 290 public Button menu(String value) { 291 attr("menu", value); 292 return this; 293 } 294 295 /** 296 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-name">name</a> attribute. 297 * 298 * <p> 299 * Specifies the name of the button. This name is used when the form is submitted and 300 * can be used to access the element via the form.elements API. 301 * 302 * <p> 303 * The name should be unique within the form and should not contain spaces or special characters. 304 * 305 * @param value The name of the button for submission and API access. Can be <jk>null</jk> to unset the attribute. 306 * @return This object. 307 */ 308 public Button name(String value) { 309 attr("name", value); 310 return this; 311 } 312 313 /** 314 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-button-type">type</a> attribute. 315 * 316 * <p> 317 * Specifies the type of button and its behavior when clicked. 318 * 319 * <p> 320 * Possible values: 321 * <ul> 322 * <li><js>"submit"</js> - Submits the form (default)</li> 323 * <li><js>"reset"</js> - Resets the form to its initial state</li> 324 * <li><js>"button"</js> - Generic button with no default behavior</li> 325 * </ul> 326 * 327 * @param value The type of button and its behavior. Can be <jk>null</jk> to unset the attribute. 328 * @return This object. 329 */ 330 public Button type(String value) { 331 attr("type", value); 332 return this; 333 } 334 335 /** 336 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-button-value">value</a> attribute. 337 * 338 * <p> 339 * Value to be used for form submission. 340 * 341 * @param value 342 * The new value for this attribute. 343 * Typically a {@link Number} or {@link String}. 344 * Can be <jk>null</jk> to unset the attribute. 345 * @return This object. 346 */ 347 public Button value(Object value) { 348 attr("value", value); 349 return this; 350 } 351}