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-input-element"><input></a> 025 * element. 026 * 027 * <p> 028 * The input element represents a form control that allows users to input data. It is a void element 029 * that can take many different forms depending on the type attribute, including text fields, checkboxes, 030 * radio buttons, file uploads, and more. The input element is one of the most versatile and commonly 031 * used form controls in HTML. 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>// Text input field</jc> 038 * Input <jv>input1</jv> = <jsm>input</jsm>(<js>"text"</js>) 039 * .name(<js>"username"</js>) 040 * .placeholder(<js>"Enter your username"</js>) 041 * .required(<jk>true</jk>); 042 * 043 * <jc>// Email input with validation</jc> 044 * Input <jv>input2</jv> = <jsm>input</jsm>(<js>"email"</js>) 045 * .name(<js>"email"</js>) 046 * .placeholder(<js>"your@email.com"</js>) 047 * .autocomplete(<js>"email"</js>); 048 * 049 * <jc>// File upload input</jc> 050 * Input <jv>input3</jv> = <jsm>input</jsm>(<js>"file"</js>) 051 * .name(<js>"avatar"</js>) 052 * .accept(<js>"image/*"</js>) 053 * .multiple(<jk>true</jk>); 054 * 055 * <jc>// Checkbox input</jc> 056 * Input <jv>input4</jv> = <jsm>input</jsm>(<js>"checkbox"</js>) 057 * .name(<js>"subscribe"</js>) 058 * .value(<js>"yes"</js>) 059 * .checked(<jk>true</jk>); 060 * 061 * <jc>// Password input with pattern</jc> 062 * Input <jv>input5</jv> = <jsm>input</jsm>(<js>"password"</js>) 063 * .name(<js>"password"</js>) 064 * .pattern(<js>".{8,}"</js>) 065 * .title(<js>"Password must be at least 8 characters"</js>); 066 * </p> 067 * 068 * <p> 069 * The following convenience methods are provided for constructing instances of this bean: 070 * <ul class='javatree'> 071 * <li class='jc'>{@link HtmlBuilder} 072 * <ul class='javatree'> 073 * <li class='jm'>{@link HtmlBuilder#input() input()} 074 * <li class='jm'>{@link HtmlBuilder#input(String) input(String)} 075 * </ul> 076 * </ul> 077 * 078 * <h2 class='section'>See Also:</h2><ul> 079 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanHtml5">juneau-bean-html5</a> 080 * </ul> 081 */ 082@Marshalled(typeName = "input") 083public class Input extends HtmlElementVoid<Input> { 084 085 /** 086 * Creates an empty {@link Input} element. 087 */ 088 public Input() {} 089 090 /** 091 * Creates an {@link Input} element with the specified {@link Input#type(String)} attribute. 092 * 093 * @param type The {@link Input#type(String)} attribute. Can be <jk>null</jk> to unset the attribute. 094 */ 095 public Input(String type) { 096 type(type); 097 } 098 099 /** 100 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-accept">accept</a> attribute. 101 * 102 * <p> 103 * Specifies which file types the file input should accept. Used with <c>type="file"</c>. 104 * 105 * <p> 106 * Examples: 107 * <ul> 108 * <li><js>"image/*"</js> - Accept all image files</li> 109 * <li><js>".pdf,.doc,.docx"</js> - Accept specific file extensions</li> 110 * <li><js>"image/png,image/jpeg"</js> - Accept specific MIME types</li> 111 * </ul> 112 * 113 * @param value File type restrictions for file uploads. Can be <jk>null</jk> to unset the attribute. 114 * @return This object. 115 */ 116 public Input accept(String value) { 117 attr("accept", value); 118 return this; 119 } 120 121 /** 122 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-alt">alt</a> attribute. 123 * 124 * <p> 125 * Alternative text for image submit buttons. Used with <c>type="image"</c> to provide 126 * accessible text when the image cannot be displayed. 127 * 128 * @param value Alternative text for image submit buttons. Can be <jk>null</jk> to unset the attribute. 129 * @return This object. 130 */ 131 public Input alt(String value) { 132 attr("alt", value); 133 return this; 134 } 135 136 /** 137 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-autocomplete">autocomplete</a> attribute. 138 * 139 * <p> 140 * Controls whether the browser can automatically complete the input field. 141 * 142 * <p> 143 * Common values: 144 * <ul> 145 * <li><js>"on"</js> - Allow autocomplete (default)</li> 146 * <li><js>"off"</js> - Disable autocomplete</li> 147 * <li><js>"name"</js> - Full name</li> 148 * <li><js>"email"</js> - Email address</li> 149 * <li><js>"username"</js> - Username or login</li> 150 * <li><js>"current-password"</js> - Current password</li> 151 * <li><js>"new-password"</js> - New password</li> 152 * <li><js>"tel"</js> - Telephone number</li> 153 * <li><js>"url"</js> - URL</li> 154 * <li><js>"address-line1"</js> - Street address</li> 155 * <li><js>"country"</js> - Country name</li> 156 * <li><js>"postal-code"</js> - Postal code</li> 157 * </ul> 158 * 159 * @param value Autocomplete hint for the input field. Can be <jk>null</jk> to unset the attribute. 160 * @return This object. 161 */ 162 public Input autocomplete(String value) { 163 attr("autocomplete", value); 164 return this; 165 } 166 167 /** 168 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-autofocus">autofocus</a> attribute. 169 * 170 * <p> 171 * Automatically focuses the form control when the page loads. 172 * Only one element per page should have this attribute. 173 * 174 * @param value 175 * The new value for this attribute. 176 * Typically a {@link Boolean} or {@link String}. 177 * Can be <jk>null</jk> to unset the attribute. 178 * @return This object. 179 */ 180 public Input autofocus(Object value) { 181 attr("autofocus", value); 182 return this; 183 } 184 185 /** 186 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-checked">checked</a> attribute. 187 * 188 * <p> 189 * Whether the command or control is checked. 190 * 191 * <p> 192 * This attribute uses deminimized values: 193 * <ul> 194 * <li><jk>false</jk> - Attribute is not added</li> 195 * <li><jk>true</jk> - Attribute is added as <js>"checked"</js></li> 196 * <li>Other values - Passed through as-is</li> 197 * </ul> 198 * 199 * @param value 200 * The new value for this attribute. 201 * Typically a {@link Boolean} or {@link String}. 202 * Can be <jk>null</jk> to unset the attribute. 203 * @return This object. 204 */ 205 public Input checked(Object value) { 206 attr("checked", deminimize(value, "checked")); 207 return this; 208 } 209 210 /** 211 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-dirname">dirname</a> attribute. 212 * 213 * <p> 214 * Specifies the name of a hidden form field that will be submitted along with the input value, 215 * containing the text direction (ltr or rtl) of the input content. 216 * 217 * <p> 218 * This is useful for forms that need to preserve text direction information when submitted. 219 * The hidden field will contain either "ltr" or "rtl" based on the input's direction. 220 * 221 * @param value The name of the hidden field for directionality information. Can be <jk>null</jk> to unset the attribute. 222 * @return This object. 223 */ 224 public Input dirname(String value) { 225 attr("dirname", value); 226 return this; 227 } 228 229 /** 230 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-disabled">disabled</a> attribute. 231 * 232 * <p> 233 * Whether the form control is disabled. 234 * 235 * <p> 236 * This attribute uses deminimized values: 237 * <ul> 238 * <li><jk>false</jk> - Attribute is not added</li> 239 * <li><jk>true</jk> - Attribute is added as <js>"disabled"</js></li> 240 * <li>Other values - Passed through as-is</li> 241 * </ul> 242 * 243 * @param value 244 * The new value for this attribute. 245 * Typically a {@link Boolean} or {@link String}. 246 * Can be <jk>null</jk> to unset the attribute. 247 * @return This object. 248 */ 249 public Input disabled(Object value) { 250 attr("disabled", deminimize(value, "disabled")); 251 return this; 252 } 253 254 /** 255 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fae-form">form</a> attribute. 256 * 257 * <p> 258 * Associates the input with a form element by specifying the form's ID. This allows the input 259 * to be placed outside the form element while still being part of the form. 260 * 261 * <p> 262 * The value should match the ID of a form element in the same document. 263 * 264 * @param value The ID of the form element to associate with this input. Can be <jk>null</jk> to unset the attribute. 265 * @return This object. 266 */ 267 public Input form(String value) { 268 attr("form", value); 269 return this; 270 } 271 272 /** 273 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formaction">formaction</a> attribute. 274 * 275 * <p> 276 * URL to use for form submission. 277 * 278 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 279 * @return This object. 280 */ 281 public Input formaction(String value) { 282 attr("formaction", value); 283 return this; 284 } 285 286 /** 287 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formenctype">formenctype</a> attribute. 288 * 289 * <p> 290 * Form data set encoding type to use for form submission. 291 * 292 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 293 * @return This object. 294 */ 295 public Input formenctype(String value) { 296 attr("formenctype", value); 297 return this; 298 } 299 300 /** 301 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formmethod">formmethod</a> attribute. 302 * 303 * <p> 304 * HTTP method to use for form submission. 305 * 306 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 307 * @return This object. 308 */ 309 public Input formmethod(String value) { 310 attr("formmethod", value); 311 return this; 312 } 313 314 /** 315 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formnovalidate">formnovalidate</a> 316 * attribute. 317 * 318 * <p> 319 * Bypass form control validation for form submission. 320 * 321 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 322 * @return This object. 323 */ 324 public Input formnovalidate(String value) { 325 attr("formnovalidate", value); 326 return this; 327 } 328 329 /** 330 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fs-formtarget">formtarget</a> attribute. 331 * 332 * <p> 333 * Browsing context for form submission. 334 * 335 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 336 * @return This object. 337 */ 338 public Input formtarget(String value) { 339 attr("formtarget", value); 340 return this; 341 } 342 343 /** 344 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-dim-height">height</a> 345 * attribute. 346 * 347 * <p> 348 * Vertical dimension. 349 * 350 * @param value 351 * The new value for this attribute. 352 * Typically a {@link Number} or {@link String}. 353 * Can be <jk>null</jk> to unset the attribute. 354 * @return This object. 355 */ 356 public Input height(Object value) { 357 attr("height", value); 358 return this; 359 } 360 361 /** 362 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-input-inputmode">inputmode</a> 363 * attribute. 364 * 365 * <p> 366 * Provides a hint to browsers about the type of virtual keyboard to display on mobile devices. 367 * 368 * <p> 369 * Possible values: 370 * <ul> 371 * <li><js>"none"</js> - No virtual keyboard</li> 372 * <li><js>"text"</js> - Standard text keyboard (default)</li> 373 * <li><js>"tel"</js> - Numeric keypad for telephone numbers</li> 374 * <li><js>"url"</js> - Keyboard optimized for URLs</li> 375 * <li><js>"email"</js> - Keyboard optimized for email addresses</li> 376 * <li><js>"numeric"</js> - Numeric keypad</li> 377 * <li><js>"decimal"</js> - Numeric keypad with decimal point</li> 378 * <li><js>"search"</js> - Keyboard optimized for search</li> 379 * </ul> 380 * 381 * @param value The input modality hint for mobile keyboards. Can be <jk>null</jk> to unset the attribute. 382 * @return This object. 383 */ 384 public Input inputmode(String value) { 385 attr("inputmode", value); 386 return this; 387 } 388 389 /** 390 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-list">list</a> attribute. 391 * 392 * <p> 393 * References a <c><datalist></c> element that provides predefined options 394 * for the input field. Creates a dropdown with autocomplete suggestions. 395 * 396 * @param value The ID of a datalist element (without the # prefix). Can be <jk>null</jk> to unset the attribute. 397 * @return This object. 398 */ 399 public Input list(String value) { 400 attr("list", value); 401 return this; 402 } 403 404 /** 405 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-max">max</a> attribute. 406 * 407 * <p> 408 * Maximum value. 409 * 410 * @param value 411 * The new value for this attribute. 412 * Typically a {@link Number} or {@link String}. 413 * Can be <jk>null</jk> to unset the attribute. 414 * @return This object. 415 */ 416 public Input max(Object value) { 417 attr("max", value); 418 return this; 419 } 420 421 /** 422 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-maxlength">maxlength</a> attribute. 423 * Maximum length of value. 424 * 425 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 426 * Typically a {@link Number} or {@link String}. 427 * @return This object. 428 */ 429 public Input maxlength(Object value) { 430 attr("maxlength", value); 431 return this; 432 } 433 434 /** 435 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-min">min</a> attribute. 436 * 437 * <p> 438 * Minimum value. 439 * 440 * @param value 441 * The new value for this attribute. 442 * Typically a {@link Number} or {@link String}. 443 * Can be <jk>null</jk> to unset the attribute. 444 * @return This object. 445 */ 446 public Input min(Object value) { 447 attr("min", value); 448 return this; 449 } 450 451 /** 452 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-minlength">minlength</a> attribute. 453 * 454 * <p> 455 * Minimum length of value. 456 * 457 * @param value 458 * The new value for this attribute. 459 * Typically a {@link Number} or {@link String}. 460 * Can be <jk>null</jk> to unset the attribute. 461 * @return This object. 462 */ 463 public Input minlength(Object value) { 464 attr("minlength", value); 465 return this; 466 } 467 468 /** 469 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-multiple">multiple</a> attribute. 470 * 471 * <p> 472 * Whether to allow multiple values. 473 * 474 * <p> 475 * This attribute uses deminimized values: 476 * <ul> 477 * <li><jk>false</jk> - Attribute is not added</li> 478 * <li><jk>true</jk> - Attribute is added as <js>"multiple"</js></li> 479 * <li>Other values - Passed through as-is</li> 480 * </ul> 481 * 482 * @param value 483 * The new value for this attribute. 484 * Typically a {@link Boolean} or {@link String}. 485 * Can be <jk>null</jk> to unset the attribute. 486 * @return This object. 487 */ 488 public Input multiple(Object value) { 489 attr("multiple", deminimize(value, "multiple")); 490 return this; 491 } 492 493 /** 494 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-fe-name">name</a> attribute. 495 * 496 * <p> 497 * Name of form control to use for form submission and in the form.elements API. 498 * 499 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 500 * @return This object. 501 */ 502 public Input name(String value) { 503 attr("name", value); 504 return this; 505 } 506 507 /** 508 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-pattern">pattern</a> attribute. 509 * 510 * <p> 511 * Specifies a regular expression that the input's value must match for the form to be valid. 512 * Works with the <c>title</c> attribute to provide user feedback. 513 * 514 * @param value A regular expression pattern (e.g., <js>"[0-9]{3}-[0-9]{3}-[0-9]{4}"</js> for phone numbers). Can be <jk>null</jk> to unset the attribute. 515 * @return This object. 516 */ 517 public Input pattern(String value) { 518 attr("pattern", value); 519 return this; 520 } 521 522 /** 523 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-placeholder">placeholder</a> attribute. 524 * 525 * <p> 526 * Provides a hint to the user about what to enter in the input field. 527 * The placeholder text appears when the field is empty and disappears when the user starts typing. 528 * 529 * @param value Hint text to display in the empty input field. Can be <jk>null</jk> to unset the attribute. 530 * @return This object. 531 */ 532 public Input placeholder(String value) { 533 attr("placeholder", value); 534 return this; 535 } 536 537 /** 538 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-readonly">readonly</a> attribute. 539 * 540 * <p> 541 * Whether to allow the value to be edited by the user. 542 * 543 * @param value If <jk>true</jk>, adds <c>readonly="readonly"</c>. Can be <jk>null</jk> to unset the attribute. 544 * @return This object. 545 */ 546 public Input readonly(boolean value) { 547 if (value) 548 value("value"); 549 return this; 550 } 551 552 /** 553 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-readonly">readonly</a> attribute. 554 * 555 * <p> 556 * Makes the input field read-only, preventing user modification while still allowing 557 * the value to be submitted with the form. 558 * 559 * @param value If <jk>true</jk>, makes the input read-only. Can be <jk>null</jk> to unset the attribute. 560 * @return This object. 561 */ 562 public Input readonly(Object value) { 563 attr("readonly", value); 564 return this; 565 } 566 567 /** 568 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-readonly">required</a> attribute. 569 * 570 * <p> 571 * Indicates that the input field must be filled out before the form can be submitted. 572 * Browsers will show validation messages for empty required fields. 573 * 574 * @param value If <jk>true</jk>, makes the input required for form submission. Can be <jk>null</jk> to unset the attribute. 575 * @return This object. 576 */ 577 public Input required(Object value) { 578 attr("required", value); 579 return this; 580 } 581 582 /** 583 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-size">size</a> attribute. 584 * 585 * <p> 586 * Size of the control. 587 * 588 * @param value 589 * The new value for this attribute. 590 * Typically a {@link Number} or {@link String}. 591 * Can be <jk>null</jk> to unset the attribute. 592 * @return This object. 593 */ 594 public Input size(Object value) { 595 attr("size", value); 596 return this; 597 } 598 599 /** 600 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-src">src</a> attribute. 601 * 602 * <p> 603 * Address of the resource. 604 * 605 * @param value 606 * The new value for this attribute. 607 * Typically a {@link URL} or {@link String}. 608 * Can be <jk>null</jk> to unset the attribute. 609 * @return This object. 610 */ 611 public Input src(Object value) { 612 attr("src", value); 613 return this; 614 } 615 616 /** 617 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-step">step</a> attribute. 618 * 619 * <p> 620 * Granularity to be matched by the form control's value. 621 * 622 * @param value The new value for this attribute. Can be <jk>null</jk> to unset the attribute. 623 * @return This object. 624 */ 625 public Input step(String value) { 626 attr("step", value); 627 return this; 628 } 629 630 /** 631 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-type">type</a> attribute. 632 * 633 * <p> 634 * Specifies the type of form control to display. 635 * 636 * <p> 637 * Common values: 638 * <ul> 639 * <li><js>"text"</js> - Single-line text input (default)</li> 640 * <li><js>"password"</js> - Password input (characters are masked)</li> 641 * <li><js>"email"</js> - Email address input with validation</li> 642 * <li><js>"number"</js> - Numeric input with spinner controls</li> 643 * <li><js>"tel"</js> - Telephone number input</li> 644 * <li><js>"url"</js> - URL input with validation</li> 645 * <li><js>"search"</js> - Search input field</li> 646 * <li><js>"date"</js> - Date picker</li> 647 * <li><js>"time"</js> - Time picker</li> 648 * <li><js>"datetime-local"</js> - Date and time picker</li> 649 * <li><js>"checkbox"</js> - Checkbox input</li> 650 * <li><js>"radio"</js> - Radio button input</li> 651 * <li><js>"file"</js> - File upload input</li> 652 * <li><js>"submit"</js> - Submit button</li> 653 * <li><js>"button"</js> - Generic button</li> 654 * <li><js>"reset"</js> - Reset form button</li> 655 * <li><js>"hidden"</js> - Hidden input field</li> 656 * </ul> 657 * 658 * @param value The input type for the form control. Can be <jk>null</jk> to unset the attribute. 659 * @return This object. 660 */ 661 public Input type(String value) { 662 attr("type", value); 663 return this; 664 } 665 666 /** 667 * <a class="doclink" href="https://www.w3.org/TR/html5/forms.html#attr-input-value">value</a> attribute. 668 * 669 * <p> 670 * Value of the form control. 671 * 672 * @param value 673 * The new value for this attribute. 674 * Typically a {@link Number} or {@link String}. 675 * Can be <jk>null</jk> to unset the attribute. 676 * @return This object. 677 */ 678 public Input value(Object value) { 679 attr("value", value); 680 return this; 681 } 682 683 /** 684 * <a class="doclink" href="https://www.w3.org/TR/html5/embedded-content-0.html#attr-dim-width">width</a> attribute. 685 * 686 * <p> 687 * Horizontal dimension. 688 * 689 * @param value 690 * The new value for this attribute. 691 * Typically a {@link Number} or {@link String}. 692 * Can be <jk>null</jk> to unset the attribute. 693 * @return This object. 694 */ 695 public Input width(Object value) { 696 attr("width", value); 697 return this; 698 } 699}